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Foreword 




CBASIC® is a comprehensive and versatile programming language for developing 
professional microcomputer software. Software developers worldwide have selected 
CBASIC for its capacity to quickly produce reliable, maintainable programs in an 
enhanced programming environment. CBASIC combines the power of a structured, 
high-level language with the simplicity of BASIC to provide a serious development tool 
that is easy to learn and easy to use. 

If you are a newcomer to data processing, read an introductory text on BASIC first. 
All you need is an understanding of elementary programming concepts and a familiarity 
with BASIC terminology to learn CBASIC. 

The CBASIC Language Reference Manual covers CBASIC and CBASIC-86™. 

■ CBASIC runs under the CP/M®, MP/M™, and CP/NET® operating systems for 
computers based on the Intel® 8080, 8085 or the Zilog Z80® microprocessor. 

■ CBASIC-86 runs under the CP/M-86® or MP/M-86™ operating systems for 
computers based on the Intel 8086 microprocessor. 

Section 6 discusses the minor differences between the two versions of CBASIC. 

At the end of Section 1 is a demonstration program that you can compile and run by 
following a few simple steps. The rest of the manual covers three main topics: CBASIC 
language definition, machine dependencies, and the Compiler and Interpreter. 

■ Sections 2, 3, and 4 define the CBASIC language. 

■ Section 5 covers input and output. 

■ Section 6 discusses assembly language interfacing and other machine-dependent 
topics. 

■ Section 7 discusses the Compiler, run-time Interpreter, and Cross-reference Lister. 
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Section 1 
Getting Started With CBASIC 



1.1 CBASIC Components 

The CBASIC system has two main components: the Compiler and the run-time 
Interpreter. CBASIC also provides a Cross-reference Lister. 

■ The CBASIC Compiler translates a source program into intermediate code. 
Source programs must be in .BAS files. The intermediate files are .INT files. 

■ The run-time Interpreter executes the .INT file that the Compiler generates. 

■ The Cross-reference Lister produces an alphabetized list of identifiers used in 
your CBASIC program. The Cross-reference Lister is a utility program provided 
as a convenience. It does not affect your programs. 



W 



1.2 Program Structure 

CBASIC has features found in high-level languages, such as structured statements, 
functions, complex expressions, and data types. Some other CBASIC features are parameter 
passing, local and global variables, easy access to the operating system, and chaining 
between programs. 

CBASIC requires no line numbers and allows the free use of commas, spaces, and 
tabs to make your programs more readable. A statement number or label is needed 
only when the statement is referenced from another location in the program. CBASIC 
allows integers, decimal fractions and exponential numbers as statement labels, as in 
the following examples: 

1 PRINT "THESE ARE MALID LINE NUMBERS" 

INPUT "ENTER A NUMBER: "5N 

100 GO TO 1 ♦ 

100,0 END 



1.2 Program Structure 



21.543 A$ = NAME$ 
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CBASIC statement labels do not have to be sequential. The Compiler treats the labels 
as strings of characters, not as numeric quantities. For example, the two labels 100 
and 100.0 are distinct CBASIC statement labels. The maximum length for a statement 
label is 31 characters. 

CBASIC statements can span more than one line. Use the backslash character, \, to 
continue a CBASIC statement on the next line. The Compiler ignores any character 
that follows a backslash on the same line. The backslash does not work as a continuation 
character if used within a string constant. The following example demonstrates the 
continuation character: 

IF X = 3 THEN \ 

PRINT "THE VALUES ARE EQUAL" \ 
ELSE \ 

GDSUB 1000 

In most cases, you can write multiple statements on the same line. Use a colon, :, 
to separate each command that appears on one line. However, the statements DIM, 
IF, DATA, and END cannot appear on one line with others. The following example 
demonstrates multiple statements on one line: 

PRINT TA5( 10 );")<": READ #HNAME$: GOTO 1000 

Use comments or remarks freely to document your programs. The REM statement 
allows unlimited program notation. Also, use spaces freely to enhance readability of 
your programs. Comments, long variable names, and blank spaces do not affect the 
size of your compiled program. 



1.3 A Demonstration Program 

The following demonstration program should help you get over the initial hurdle of 
compiling and running your first CBASIC program. You should already be familiar 
with CP/M and a text editor. The following instructions are for CBASIC on a CP/M- 
based system with two floppy-disk drives. 
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1.3 A Demonstration Program 



Make a back-up copy of your master CBASIC disk. Place your operating system 
disk into drive A and a copy of your CBASIC disk into drive B. 

1. Write the program. 

Using your text editor, create a file named TEST.BAS on your CBASIC disk 
in drive B. Enter the following program into TEST.BAS exactly as it appears 
below: 

PRINT 

FOR II = 1 TO 10 

PRINT III "TESTING CBASIC!" 
NEXT II 
PRINT 

PRINT "FINISHED" 
END 




2. Compile the program. 

To start the CBASIC Compiler, enter the following command. Be sure drive B 
is the default drive. 

B>C5AS TEST 

The Compiler assumes a filetype of .BAS for the file you specify in the Compiler 
command. A sign-on message, a listing of your source program, and several 
diagnostic messages display on your terminal. The message NO ERRORS 
DETECTED indicates a successful compilation. The Compiler creates an inter- 
mediate file for the TEST.BAS program. The directory for disk B should have 
the new file TEST.INT. 



1.3 A Demonstration Program 



3. Run the program. 
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To start the run-time Interpreter, enter the following command. Be sure drive 
B is the default drive. 




Q>CRUN TEST 

The following output should appear on your terminal: 

CRUN I'er, 2* XX Serial No, 000-00000 Copyright (c) 
1982 Digital Research* Inc. All rights reserued 



TESTING 
TESTING 
TESTING 
TESTING 
TESTING 
TESTING 
TESTING 
TESTING 
TESTING 



CBASIC 
C5ASIC 
CBASIC 
CBASIC 
CBASIC 
CBASIC 
CBASIC 
CBASIC 
CBASIC 



10 TESTING CBASIC 



FINISHED 



Minor differences appear in the sign-on message for the different versions of 
CBASIC. 

End of Section 1 





Section 2 

Names, Numbers, and 

Expressions 




CBASIC has three principal data types: integers, real numbers, and strings. CBASIC 
also supports dynamic, multidimensional arrays of all three data types. Each data type 
has a distinct form for identifiers. Numeric constants can be written in several forms. 

CBASIC has a large set of operators for building expressions with variables, constants, 
and functions of the three data types. By converting from one type to another, where 
necessary, CBASIC allows real numbers to be mixed with integers in most expressions. 



2.1 Identifiers 

An identifier can be any length, as long as it fits on one line. Only the first thirty- 
one characters are meaningful for distinguishing one name from another. The first 
character must be a letter, the remaining characters can be letters, numerals, or periods. 
The final character in an identifier determines which data type it represents. 

■ Identifiers ending with $ are for strings. 

■ Identifiers ending with % are for integers. 

■ Identifiers without a $ or % are for real numbers. 

The Compiler converts lower-case letters to upper-case letters unless toggle D is set. 

Names for variables cannot begin with the letters FN. Names for user-defined func- 
tions always begin with FN. 

The following are examples of valid CBASIC identifiers. 

NEW.SUM 



2.1 Identifiers 

f i 1 8 1 2 . n a in e $ 

Payroll . I d e n t i f i c a t i o n ♦ N u m b e r "/» 
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2.2 Strings 

String constants are delimited by quotes. A string constant can have zero or more 
printing characters, as long as the string fits on a single line. The \ character has no 
special meaning inside a string constant. Two adjacent quotes represent one printed 
quote in the string. 

For example, the string constant 

'Hello.'" 1 said Tom." 

is stored internally as the string: 

" H e 1 1 o > " said Tom* 

Although string constants cannot contain control characters and must fit on one 
line, string variables are more flexible. Internally, a string can have from to 255 
characters. Each character takes up one byte. The first byte in the string data area 
contains the length of the string. To build long strings, or to embed control characters 
in strings, use string expressions, as described later in this section, and string functions, 
as described in Section 3. 

The following are examples of valid CBASIC string constants: 

"July 4» 1776" 

" E n i e r v o u r name please:" 

" " " \ " " has no special meaning inside a s t r i n 3 ♦ " 

" " — the null string 
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2.3 Numbers 



2.3 Numbers 



Two types of numeric quantities are supported by CBASIC: real and inteser A r,,\ 
constant ,s wrmen in either fixed format or exponential notation In both cats 
contatns from one to fourteen digits, a sign, and a decimal poL In exponenfi 

should not be confused wirTtbe o", s.gn f toZZPgZZ * "* 

lauuainea internally by CBASIC, more digits can be included in a real mn^nf R«oi 
constants are rounded to fourteen significant digits. ' ^ 

A constant is treated as an integer if the constant does not contain an embedded 
decimal point, is not m exponential notation, and ranges from -32768 to +32767 

Integer constants can also be expressed as hexadecimal or binary constants The 

Te^s e IZ n T I eX ; deC,n ? al COnStant The lettCr B teri ™ ab^ conJnt 
Ihe first digit of a hexadecimal constant must be numeric For examnle K " K 

adecimal is OFFH, not FFH. FFH is a valid identifier. P ' '*" 

Hexadecimal and binary constants do not contain a decimal point The value retain^ 
is the sixteen least-significant bits of the number specified. ^ 

The" te^mTr^ thC T S real n u UmbCr 3nd floatln 8-P^nt number are interchangeable 
I he term numeric applies to either a real or integer quantity. angeaoie. 

Examples of valid numbers are: 

1 ' 1 .0 » -99 , 123459,789 
1.993, .01, 4 E 1 2 > 1 ♦ 7 7 E - 9 
1 . 5 E + 3 is equivalent to 1 5 ♦ 
1 ♦ 5 E - 3 is equivalent to . 1 5 
labOH, 101 11 HOB, OFFFFH 



2.4 Variables and Array Variables 



2.4 Variables and Array Variables 
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A variable in CBASIC represents an integer, real number, or a string, depending on 
the type of the identifier. 

Each variable has a value always associated with it during program execution. A 
string variable does not have a fixed length associated with it. Rather, as different 
strings are assigned to the variable, the storage is dynamically allocated. The maximum 
length allowed in a string variable is 255 characters. Numeric variables are initialized 
to 0. String variables are initialized to the null string. 

A variable takes the general form: 

identifier [ {subscript list ) ] 

The following are examples of variables: 




PAYMENT 

d a v ♦ o f ♦ d e p o s i t "/,, 

Array variables look like regular variables with an added subscript list. CBASIC 
arrays can hold strings, integers, or reals. As with regular variables, the type of identifier 
specifies the type of array. The subscripts specify which element in the array to reference. 

A subscript takes the general form: 

expression { , expression } 

The following examples show array variables: 

y $ ( i 1 tjltkltl 1 ) 

C0ST(3 >5) 

PCS'*. (X AXIS'*. »Y AXIS'*.) 

INCOME(AMT(CLIENT'*. ) , CURRENT . MONTH'*. ) 
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2.4 Variables and Array Variables 



The expressions in a subscript list must be numeric. Access to array elements is more 
efficient if integer expressions are used in subscript lists. If the expression is real, the 
value is rounded to the nearest integer before using the value. The subscript list indicates 
the variable is an array variable and indicates which element of the array reference. 

When subscripts are calculated, a check ensures that the element selected resides in 
the referenced array. A run-time error occurs if the element does not reside in the 
referenced array. The run-time check ensures that the location calculated is included 
in the physical storage area of the array. 

Before an array variable is referenced in a program, it must be dimensioned using 
the DIM statement. The DIM statement specifies the upper-bound of each subscript 
and allocates storage for the array. Section 3 describes the DIM statement. 

An array must be dimensioned explicitly; no default options are provided. Arrays 
are stored in row-major order. 

The subscript list is used to specify the number of dimensions and the extent of each 
dimension of the array being declared. The subscript list cannot contain a reference to 
the array being dimensioned. All subscripts have an implied lower-bound of zero. 

The same identifier can name both a variable and an array variable in the same 
program, although that is not a recommended practice. 




2.5 Expressions 

The following are examples of expressions: 

cost + overhead * percent 

a * b / c ( 1 ♦ 2 + x y z ) 

1 a s t ♦ n a m e $ + " t " + f i r s t ♦ n a m e $ 

i n d e x "/„ + 1 

Expressions consist of algebraic combinations of function references, variables, con- 
stants and operators. Expressions evaluate to an integer, real, or string value. Table 
2-1 gives the hierarchy of operators. 



2.5 Expressions 
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Table 2-1. Hierarchy of Operators 



Hierarchy 


Operator 


Definition 


1 
2 


u 


balanced parentheses 
power operator 


Arithmetic Operators 


3 
4 


V 

+, - 


multiply, divide 
plus, minus 


Relational Operators 


5 


< 
< = 

> 
> = 

<> 


LT (less than) 

LE (less than/equal to) 

GT (greater than) 

GE (greater than/equal to) 

EQ (equal to) 

NE (not equal) 


Logical Operators 


6 

7 
8 
9 


NOT 

AND 

OR 

XOR 






Arithmetic and relational operations work with integers and real numbers. An integer 
value converts to a real number if the operation combines a real and integer value. 
The operation then uses the two real values, resulting in a real value. This is mixed- 
mode arithmetic. 



Mixed-mode operations require more time to execute because the Compiler generates 
more code. A mixed-mode expression always evaluates to a real value. 

The power operator calculates the logarithm of the number being raised to the power 
if real values are used. A warning results when the number to the left of the operator 
is negative because the logarithm of a negative number is undefined. The absolute 
value of the negative quantity calculates the result. The exponent is positive or negative. 
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2.5 Expressions 
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If both values used with the power operator are either integer constants or integer 
variables, the result is calculated by successive multiplication. This allows a negative 
integer number to be raised to an integer power. With integers, if the exponent is 
negative, the result is zero. In all cases, A is 1 and * X, where X is not equal to 
0, is 0. 

If the exponent is an integer but the base is real, the integer is converted to a real 
value before calculating the result. Likewise, if the exponent is real but the base is an 
integer quantity, the result is calculated using real values. 

String variables can only be operated on by the relational operators and the concatena- 
tion operator +. Mixed string and numeric operations are not permitted. The mnemonic 
relational operators (LT, LE, etc.) are interchangeable with the corresponding algebraic 
operators (<, <=, etc.). 

Relational operators result in integer values. A is false and a -1 is true. Logical 
operators AND, NOT, OR, and XOR operate on integer values and result in an integer 
number. If a real value is used with logical operators, it is first converted to an integer. 

If a numeric quantity exceeds the range from 32,767 to -32,768, it cannot be rep- 
resented by a 16-bit two's complement binary number. Logical operations on such a 
number produce unpredictable results. 

These are results of logical operations: 



12 AND 3 
NOT -1 

12 OR 3 



= 
= 
= 15 



12,4 XOR 3,2 =15 



1 100B AND 0101B = 4 

NOT 3H = -4 

OCH OR 5H =1,3 

12. a XOR 3,7 =8 




Efficiency is increased by using integer expressions for relational tests and logical 
operations. Programs written in Version 1 of CBASIC should be converted to use 
integer variables wherever possible. 

Note: if a series of digits contains no decimal point or ends in a decimal point, CBASIC 
attempts to store it as an integer. If the resulting number is in the range of CBASIC 
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integers, it is treated as an integer. If the constant is then required in an expression as 
a real number, the constant converts to a real number at run-time. For example, 

X = X + 1. 

causes the integer constant 1. to be converted to a real value before adding it to X. 
To eliminate this extra conversion, embed the decimal in the number as shown below: 

X = X + 1.0 

Actually, there is very little difference in execution speed. A similar situation exists 
in the following statement: 

Y% = X% + 1.0 

In this case, the X% is converted to a real number before adding it to the real constant. 
The result is then converted back to an integer prior to assignment to Y%. 

Generally you should avoid mixed-mode expressions whenever possible, and not use 
real constants with integer variables. Most whole numbers used in a program are stored 
as integers. This provides the most effective execution. 

If an overflow occurs during an operation between real values, a warning is printed. 
Execution continues, with the result of the operation set to the largest real number. 

In the case of integers, no checking for overflow is performed because this reduces the 
efficiency of integer operations. The calculated value returns a negative number if the 
results of an integer operation fall outside the range of integer values, greater than 32767 
and less than -32767. 




End of Section 2 
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Section 3 
Statements and Functions 



This section uses the following typographical conventions to highlight the various 
elements that make up each statement and function. 

■ CAPS indicate CBASIC keywords. 

■ Lower-case letters identify variables. 

■ Italics indicate syntactic items, such as expressions. 

■ Items enclosed in square brackets [ ] are optional. 

■ Items enclosed in braces { } are optional and can be repeated. 
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ABS Function 

The ABS(x) function returns the absolute value of the expression x. 

Syntax: 

y = ABS ( numeric expression ) 

Explanation: 

The ABS function returns a floating-point number. If the expression is an integer, 
CBASIC converts it to floating point. If the expression is positive or zero, the function 
returns the value unchanged. Otherwise, the function returns the negative of the value. 

Examples: 

DISTANCE = ABS(START - FINISH) 
IF ABS ( DELTA, X) <= LIM THEN STOP 
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ATN Function 

The ATN(x) function returns the arc tangent of x. 

Syntax: 

y = ATN (numeric expression) 

Explanation: 

The result of ATN(x) is the angle, expressed in radians, whose tangent is x. The 
result is a floating-point number. 

Examples: 

RADIANS = ATN(X) 

IF ATN(N) < PI/2,0 THEN\ 

PRINT "ANGLE LESS THAN 90 DEGREES" 
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CALL Statement 

The CALL statement links to a machine language subroutine. 

Syntax: 

CALL numeric expression 

Explanation: 

The statement calls the machine language subroutine address specified by the expres- 
sion. If the value is a real number, CBASIC rounds it to the nearest integer. 

Section 6 discusses machine language interfacing and addressing on different micro- 
processors. 

Examples: 

See Section 6.5 for examples of the CALL statement. 
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The CHAIN statement transfers control to another program. 




Syntax: 



CHAIN filespec 

Explanation: 

The CHAIN statement transfers control to the program specified in the string expres- 
sion. The expression must evaluate to a file specification. The drive name is optional; 
the default is the currently logged-in drive. The file must be of type INT. Even if a 
different file type is specified, the statement only recognizes type INT files. 

Examples: 

CHAIN "B: PAYROLL" 
CHAIN SEGMENT$ 
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CHR$ Function 




CHR$ Function 

The CHR$(x) function returns the character whose ASCII decimal value is x. 

Syntax: 

a$ = CHR$ ( numeric expression ) 

Explanation: 

The result of CHR$ is a single-character string, whose ASCII value is equal to the 
value of the input expression. If the expression is in floating point, CBASIC converts it to 
an integer. 

Appendix D lists the character set and their ASCII values. Use CHR$ to send control 
characters to an output device, as shown in the examples below. 

Examples: 

PRINT CHR$(7) REM BEEP THE TERMINAL 

PRINT CHR$(LINEFEEDX) 

IF CHR$(INP( IN*PORT%) ) = "A" THEN GOSUB 100 
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CLOSE Statement 

CLOSE Statement 

The CLOSE statement deactivates open files. 
Syntax: 

CLOSE file number {,file number} 
Explanation: 



The CLOSE statement deactivates an open file. This means that the file is no longer 
available for input or output. The specified file must have been activated by a CREATE, 
FILE, or OPEN statement before using CLOSE. 

Each expression refers to the identification number of an active file. The expression 
must be an integer ranging from 1 to 20. CBASIC converts real numbers to integers. 

The CLOSE statement closes the file, releases the file number, and reallocates all 
buffer space used by the file. IF END statements assigned to closed files have no further 
effect. 

A STOP statement automatically closes all active files. A CTRL-Z entered in response 
to an INPUT statement closes all active files. A CTRL-C does not close active files. 
Run-time errors do not close active files. 

Examples: 

CLOSE FILE ♦NO'/. 

CLOSE NEW. MASTER. FILE*.* OLD . MASTER ♦ F I LEZ t UPDATE. 8127, 

FOR XX = 1 TO NO, OF ♦WORK ♦FILES'/. 

CLOSE XI 
NEXT XX 
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COMMANDS Function 



COMMANDS Function 



The COMMANDS function returns a string containing the parameters from the 
command line that started the program. 

Syntax: 

a$ = COMMANDS 

Explanation: 

COMMANDS returns the command line from the operating system, minus the 
program name. The word TRACE and any associated line numbers are not included 
in the string if the TRACE option is in the command line. 

COMMANDS removes leading blanks and converts alphabetic characters to upper- 
case. The maximum length of the returned string is 50 characters. 

Use the COMMANDS function anywhere in the program, any number of times, 
and with any program loaded by a CHAIN statement. 

Section 7 discusses command lines in more detail. 

Examples: 

IF COMMAND* = " " THEN STOP 
If any of the following commands starts a CBASIC program, 

CRUN PAYROLL NOCHECKS TOTALS 
CRUN8B payroll no check 5 totals 
CRUN8B payroll trace no checks totals 
the resulting string from COMMANDS is: 
NOCHECKS TOTALS 
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The COMMON statement specifies variables that are common to the main program 
and all programs executed through CHAIN statements. 




Syntax: 

COMMON variable { , variable } 

Explanation: 

A COMMON statement is a nonexecutable statement that specifies the listed var- 
iables common to the main program, and all programs executed through a CHAIN 
statement. If present, COMMON statements must be the first statements in a program. 
However, blank lines and REM statements can precede COMMON statements. 

If the main program contains COMMON statements, each chained program must 
have COMMON statements that match those in the main program. Matching means 
that there are the same number of variables in each COMMON statement, and that 
the type of each variable in the COMMON statement of the main program matches 
the type of each variable in the COMMON statement of the chained program. Also, 
dimensioned variables must have the same number of subscripts in each program. 

Specify array variables by placing the number of subscripts in parentheses after the 
array name. 

Examples: 

COMMON ){ f Y ♦ A(3) t B$(2) 

This statement specifies that X and Y are nonsubscripted real variables, common to all 
chained programs. A and B$ are arrays accessible by all programs. A has three subscripts, 
while B$ has two. The COMMON statement does not indicate the size of any subscript. 



Note: the specification of an array in a COMMON statement is not generally the same 
as the specification in a DIM statement (see Section 2.4). 

COMMON A(3) 

can be used with 






*$ -Vf'.-^fa, 
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COMMON Statement 




DIM A(20»30»20) 

However, an error occurs if you use COMMON A (3) with: 

DIM A(3) 

Note: the array must be created using the DIM statement before accessing an element 
in an array in COMMON. 

The first program that requires access to the array must ensure that a DIM statement, 
which specifies the desired range for each subscript, is executed. Subsequent programs 
can access this array with the data remaining unchanged through the chaining process. 
If a subsequent program executes a DIM statement for this array, the data in the array 
is lost; in other words, the array is reinitialized. However, with string arrays, elements 
in the array are not released from memory. 

You should set elements of string arrays to null strings before executing a second 
DIM statement for the array. 
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CONCHAR% Function 

CONCHAR% reads one character from the console device. 

Syntax: 

i% = CONCHAR% 

Explanation: 

The value returned is an integer. The low-order eight bits of the returned value are 
the binary representation of the ASCII character input. The high-order eight bits are 
zero. 




Examples: 



i'l 



CONCHARZ 



CHAR*. = 

IF CONSTAT! THEN\ 

CHAR'*. = CONCHARZ 

IF CHAR*. = STOPCHARX THEN\ 
RETURN 
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CONSOLE Statement 
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CONSOLE Statement 

The CONSOLE statement restores printed output to the console. 
Syntax: 

CONSOLE 
Explanation: 

The console is the physical unit currently assigned to CON: by CP/M. 

If the list device print position is not 1, a carriage return and line-feed are output 
to the list device. 

The width of the console device is changed with the POKE statement. The console 
width is one byte at location 272 base 10, or 11 OH. The new console width becomes 
effective at the next execution of a CONSOLE statement. The console line width is 
initially set to 80, 50H. 

A width of zero results in an infinite width. With a zero width in effect, carriage 
returns and line-feeds are never automatically output to the console as a result of 
exceeding the line width. 

Examples: 



:C> '/fiNPOLE 



rNP.UF.P^GFX THEN' 



i ! ■ - T i i ( , ' ' it u t w ±i # [/.] n r- 
" J riSEPT NEW PAGE , 
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CONST AT% Function 

CONST AT% returns the console status as a boolean integer value. 

Syntax: 

i% = CONSTAT% 

Explanation: 

If the console device is ready, a logical true, -1, is returned, otherwise a logical false, 
0, is returned. 

Examples: 

IF CONST ATX. THEN\ 

G03UB 100 REM PROCESS OPERATOR INTERRUPT 

'-i!'ILE H u)T CONSTATS 
v.ENO 
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COS Function 

COS(x) returns the cosine of x. 
Syntax: 

y = COS (x) 
Explanation: 

The argument x is expressed in radians. The value returned hv CCK ; i u • 
an mteger, CBASIC converts it to a real number Y ^ U * ,S 

Examples: 

IF COS(ANGLE) = 0.0 THEN VERTICAL 1 /. = TRUE*. 
PRINT CONSTANT * COS < ROTATION > 




27 



CREATE Statement 



CREATE Statement 



CBASIC Language Reference Manual 



The CREATE statement is identical to an OPEN statement except that a new file is 
created on the selected drive. 




Syntax: 



CREATE filespec {RECL rec length}\ 

AS file number {BUFF number of sectors\ 
RECS size of sector) 

Explanation: 

When a file with the same name is present, the existing file is erased before the new 
file is created. 

The CREATE statement has no effect on any IF END statement currently in effect 
for the identification number assigned to the new file. 

Examples: 



WCL.FilttM 



P . \i : 'I / 



'* i LUPkLN 1" . uOnh ;: 
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DATA Statement 

DATA statements are nonexecutable statements that define string, real, and integer 
constants assigned to variables using the READ statement. Any number of DATA 
statements can occur anywhere in a program. 

Syntax: 




DATA constant {, constant} 
Explanation: 

The constants are stored consecutively in a data area as they appear in the program 
and are not syntax checked by the Compiler. Strings can be enclosed in quotation 
marks or optionally delimited by commas. 

A DATA statement must be the only statement on a line; it cannot be continued 
with a continuation character. However, all DATA statements in a program are treated 
collectively as a concatenated list of constants separated by commas. 

If a real constant is assigned to an integer variable with a READ statement, the 
constant is rounded off to the integer portion of the real number. If the value of a 
number assigned to an integer is outside the range of CBASIC integers, incorrect values 
are assigned. If a real number exceeds the range of real numbers, an overflow warning 
occurs and the largest CBASIC number is used in its place. 

Examples: 

400 DATA 332.33, 43*00B9E5» "ALGORITHM" 

DATA ONE » TWO , THREE » Q , 5 , G 
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DEF Statement 

Use the DEF statement to define both single- and multiple-statement functions. 

Syntax: 

Single: DEF FN f unction. name[(dummy arg list)] = expression 

Multiple: DEF FN function. name[{dummy arg list)] 
CBASIC statements 




RETURN 
FEND 

Explanation: 

A function definition must occur in a program before making a function reference. To 
define a function, the keyword DEF must precede the function name. CBASIC supports 
two types of function definitions: single-statement and multiple-statement. Refer to 
Section 4 for more information. 



Examples: 

Single: 

Multiple: 



DEF FN.CALC 



RND *25.0 



DEF FN, WRITE OUTPUT (OUTPUT, NOX) 

PRINT* OUTPUT, NO'Z 5 CUSTNOZ , AMOUNT 
RETURN 

FEND 
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DELETE Statement 

The DELETE statement removes the referenced files from their respective directories. 

Syntax: 

DELETE file number {,file number} 

Explanation: 

Each expression must be in the range of 1 to 20. If the number is not currently 
assigned to an active file, a run-time error occurs. The expression must be numeric. 
Real numbers are converted to integers. A string value results in an error. 

If an IF END statement is currently associated with the identification number for 
the file being deleted, the IF END is no longer in effect. 

Examples: 



DELETE 1 

DELETE FILE.NO'^, OUTPUT ♦ F I LE , NO*. 

11 = 

WHILE 11 < NO.OF.WORKFILESX 

11 = 11 + 1 

DELETE 11 
WEND 
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DIM Statement 

The DIM statement dynamically allocates space for an array. 

Syntax: 

DIM identifier {subscript list) 

{^identifier {subscript list)} 

Explanation: 

A DIM statement is an executable statement; each execution allocates a new array. 
Before CBASIC references an array variable in a program, the variable must be dimen- 
sioned using the DIM statement. The DIM statement specifies the upper-bound of each 
subscript and allocates storage for the array. 

The DIM statement dynamically allocates space for numeric or string arrays. If the 
array contains numeric data, the previous array is deleted before allocating space for 
a new array. If the array is string, each element must be set to a null string before 
reexecuting the DIM statement to regain the maximum amount of storage. 

Elements of string arrays are any length up to 255 bytes, and change in length as 
different values are assumed. Initially, numeric arrays are set to zero and all elements 
of string arrays are null strings. 

Examples:, 

DIM A ( 1 ) 

DIM ACCOUNTS* ( 100) , ADDRESS* ( 100) ,NAME$( 100) 
DIM Ql(2 >5 tlO) t SALES, PERSONS (STAFF, SIZED 
DIM )(( A7, ( 11) ,MZ »NZ) 
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END Statement 

The END statement terminates a source program. 

Syntax: 

END 

Explanation: 

The END statement is a directive to the Compiler indicating an end to the source 
program. The Compiler ignores any statements that follow an END statement. 

An END statement cannot appear on the same line with other statements. 

Examples: 

500 END 
END 
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EXP Function 

EXP returns the value of the irrational constant e, raised to the power given by x. 
Syntax: 

y = EXP(x) 

Explanation: 

The value returned by EXP is real. If x is an integer, CBASIC converts it to a real 
number. 

Examples: 

Y = A * EXP(B>a, ) 

E = EXP(1) REM CONSTANT E = 2,7182 
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A FILE statement opens an existing file for reading or updating. If the file does not 
exist, the FILE statement creates it. 




Syntax: 



FILE filespec [{rec length)} 
{, filespec [{rec length)}} 

Explanation: 

The filespec contains the name of the file to be accessed. As each file is activated, 
the file is assigned the next unused file number starting with 1 . If all 20 numbers are 
assigned, an error occurs. 

The record length must be a numeric expression. Real numbers are converted to 
integers. A string value causes an error. 

The variable must not be subscripted, and it must be string. It cannot be literal or 
an expression. 

Examples: 

FILE NAME* 

FILE FILE»NAME$(REC.LEN%) 




36 




CBASIC Language Reference Manual FLOAT Function 

FLOAT Function 

FLOAT(i%) converts the argument i% to a real value. 

Syntax: 

y = FLOAT(i%) 

Explanation: 

The argument should be numeric. If i% is real, CBASIC first converts it to an integer, 
and then back to a real number. 

Examples: 

AMOUNT = FLOAT (COST'*,) 

POSITION = SIN(FLOAT( ANG7.) ) * OFFSET 
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The FOR statement controls a FOR/NEXT loop. 
Syntax: 

FOR index = numeric exp. TO 
numeric exp [STEP numeric exp.] 

Explanation: 

Execution of all statements between the FOR statement and its corresponding NEXT 
statement repeats until the indexing variable, incremented by the STEP expression after 
each iteration, reaches the exit criteria. 

If the STEP expression is positive, the loop exit criteria is met when the index exceeds 
the value of the TO expression. If the STEP expression is negative, the index must be 
less than the value of the TO expression for the exit criteria to be satisfied. 

The index cannot be an array variable initially set to the value of the first expression. 
Both the TO and STEP expressions are evaluated on each loop; all variables associated 
with these expressions can change in the loop. 

Also, the index can be changed during execution of the loop. The type of the index 
can be real or integer, but all expressions must be the same. If any of the expressions 
are string, an error occurs. Particular care should be taken to ensure proper matching 
of the expression types. For example, 

FOR 11 = 1 TO DONE 

generates unnecessary code because DONE is real, but 1% and 1 are integers. Here is 
a more subtle example, 

FOR I = 1 ♦ TO DONE 

where I and DONE are real, but 1. is an integer. 

There is one situation when a FOR statement, which appears valid, generates Com- 
piler error FE. This occurs if the type of the expression following the TO is not the 
same as the type of the loop index variable. 
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For example, 

FOR I = 1 TO 13 STEP 3 

results in an FE error because the index variable I is real, but the value following the 
TO is an integer. Changing the index to 1% eliminates the error. 

If you omit the STEP clause, a default value of one is assumed. The type of the STEP 
expression in this case is the same as the type of the index. 

The statements within a FOR loop are always executed at least once. 

If you want a step of one, omit the STEP clause. The execution is much faster because 
fewer run-time checks are made. Also, less intermediate code is produced. Execution 
speed also substantially improves if all the expressions are integer. 

Examples: 



FOR INDEX'*. = 1 TO 10 

SUM = SUM + VECTOR < INDEX"*.) 
NEXT INDEX'*. 

FOR P0SITI0N=MARGIN+TABS TO PAPER.WIDTH STEP TABS 

PRINT TAB(POSITION) ;SET,TAB$; 
NEXT POSITION 

Note: In the CP/M-86 implementation of CBASIC, the upper limit for an integer 
index variable in a FOR loop is 32766. A larger value causes an infinite loop. 
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FRE Function 

FRE returns the number of bytes of unused space in the free storage area. 
Syntax: 

y = FRE 
Explanation: 

The value returned by FRE is a floating-point number. 
Examples: 
); =FRF 




RE :' 500.0 THEN GOSUB 10 REM PRINT WARNING 
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GOSUB Statement 



The GOSUB statement transfers statement execution to a statement specified by a 
reference to a label. 

Syntax: 

GOSUB stmt number 

GO SUB stmt number 

Explanation: 

In a GOSUB or GO SUB statement, CBASIC saves the location of the next sequential 
instruction on the return stack. Control then transfers to the statement labeled with the 
statement number following the GOSUB. A subroutine call can be nested 20 deep. See 
the RETURN statement for more information. 



Examples: 

GOSUB 700 

PRINT "BEFORE TABLE" 

GOSUB 200 REM PRINT THE TABLE 

PRINT "AFTER TABLE" 

STOP 

200 REM PRINT THE TABLE 

FOR INDEX 1 /. = 1 TO TABLE . S 1 ZE/ 
PRINT TABLE ( INDEX'/ ) 

NEXT INDEX/, 

RETURN 
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The GOTO statement transfers execution to a statement identified by a statement 
number. 

Syntax: 

GOTO stmt number 

GO TO stmt number 

Explanation: 

Following a GOTO or GO TO statement, execution continues at the statement 
labeled with the statement number. If the statement number branched to is not an 
executable statement, execution continues with the next executable statement after the 
statement number. 

If control is transferred to a nonexisting statement number, an error occurs. 

Examples: 

80 GO TO 35 

GOTO 100,5 
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IF Statement 

Syntax: 

IF variable THEN statement list 

[ELSE statement list] 

IF variable THEN stmt number 

Explanation: 

An IF statement expression is usually a logical expression evaluating to either true 
(-1) or false (0). However, CBASIC accepts any numeric expression of type integer, 
treating a value other than zero as true. This reduces both execution time and inter- 
mediate file size generated by the Compiler. If the expression is real, the value is rounded 
and converted to an integer. A string expression results in an error. 

A statement list is composed of one or more statements where a colon separates 
each pair of statements. The colon is not required after the THEN, nor is it required 
before or after the ELSE; it only separates statements. 

An IF statement must be the first statement on a line; it cannot follow a colon. 
Therefore, IF statements cannot be nested. 

Examples: 

IF ANSWER$="YES" THEN GOSUB 500 

IF DIMENSIONS. WANTED'/. THEN PRINT LENGTH , HEIGHT 

IF VALID'/ THEN \ 

PRINT MSG$(CURRENT.MSG/,) :\ 

GOSUB 200 :\ UPDATE RECORD 

GOSUB 210 :\ WRITE RECORD 

NO . OF . REC0RDS7, = N0 ♦ OF . RECORDS'/. + 1 : \ 

RETURN 




IF X > 3 THEN X = : Y = : 



= O 



IF YES'/ = TRUE/, THEN PRINT MSG$(1) \ 
ELSE PRINT MSG$(2) 
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IF TIME = LIMIT THEN \ 

PRINT TIME.OUT.MSG* :\ 

d^D. RESPONSES! = B AD , RESPONSES'^ 1 :\ 

QUESTION! = QUESTIONS + 1 \ 




PRINT THANKS ♦MSG* :\ 

GOSUB 1000 :\ ANALYSE RESPONSE 

GN RESPONSE'/, GOSUB \ 

2 i 20 1 t 2 2 * 203 » 204 : \ 

RETURN 

In the preceding examples, the colon separates statements in a statement list, and 
the backslash continues a statement onto another line. 

Because the Compiler ignores anything on or following the same line with the back- 
slash, comments can be inserted without using the keyword REM. 

If the value of the expression is not zero, the statements in the first statement list 
are executed. Otherwise, the statement list following ELSE is executed, if present, or 
the next sequential statement following the IF statement is executed. 

In the second example of the IF statement, when the expression is not equal to zero, 
an unconditional branch to the statement number occurs. This form of the IF statement 
does not have an ELSE clause. This variation is included in CBASIC for compatibility 
with previous versions of Basic. 
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IF END Statement 

The IF END statement allows you to process an end-of-file condition on an active 
file. 

Syntax: 

IF END # file number THEN stmt number 

Explanation: 

When an end-of-file is detected, one of two actions takes place. If an IF END 
statement is executed for the file, control transfers to the statement labeled with the 
statement number following THEN. If an IF END statement was not executed, a run- 
time error occurs. 

The IF END statement must be the only statement on a line; it cannot follow a colon 
or be part of a statement list. 

Any number of IF END statements can appear in a program for a given file. The 
most recently executed IF END is the one in effect. However, if a DELETE or CLOSE 
statement is executed, any IF END statement associated with the identification number 
is no longer effective. 

The file number must be in the range of 1 to 20. Real numbers are converted to 
integers. 

When a condition causes the transfer of control to the statement associated with an 
IF END statement, the stack is restored to the condition that existed before the statement 
causing activation of the IF END statement. 

Thus if the statement that resulted in transfer was in a subroutine, a return must be 
executed after processing the end-of-file condition. 

An IF END statement can be executed before assigning the file number to a file. A 
subsequent OPEN on a file that does not exist causes execution to continue as if an 
end-of-file were encountered. 
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In the following example, if the file MASTER.DAT does not exist on drive B, control 
transfers to statement 500.5. After a successful OPEN, an end-of-file during a READ 
continues execution with statement 500: 

IF END #MASTER,FILE,NQ'Z THEN 500,5 

OPEN "B:MASTER.DAT" AS MASTER . F I LE . NO*. BUFF G RECS 

128 

IF END n MASTER, FILE. NO'Z THEN 500 

An IF END statement can also be used when writing to a file. In this case, control 
transfers to the statement associated with the IF END when an attempt is made to 
write to the file and there is no disk space available. Part of the record created is 
written to the file. When using fixed files, the last record is rewritten after more space 
is freed. 

Examples: 



IF END # 7 THEN 500 

IF END * FILE.N07. THEN 100,1 
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The INITIALIZE statement allows the changing of diskettes during 
tion without restart ne the nn PMf in n c„^„, 8 



cution without restarting the operating system 
Syntax: 

INITIALIZE 
Explanation: 



INITIALIZE Statement 



program exe- 



dJKS aTArrot: mak,ns the diskene change - Be -» — - «*«* 



Examples: 

350 INITIALIZE 
INITIALIZE 
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INP returns the value input from the CPU I/O port specified. This function is useful 
for accessing peripheral devices directly from the CBASIC program. 

Syntax: 




y% = xINP (numeric exp.) 

Explanation: 

The argument must be numeric. For the results to be meaningful, the argument must 
range from to 255 for the 8-bit version, and from to 65535 for the 16-bit version. 
If it is a string, an error occurs. A real value is rounded to the nearest integer. 

Examples: 



PRINT INP(ADDRI) 

IF INP (255) > THEN PRINT CHR$(7) 

ON INP< INPUT. DEVICE. PORT 1 *.) GOSUB \ 

1 t 2 t 3 t 4 t 4 t 4 * 5 
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INPUT Statement 



INPUT statements accept data from the console and assign the data to program 
variables. 

Syntax: 



INPUT [prompt string ;] 

variable {, variable} 

Explanation: 

If a prompt string is present in an INPUT statement, CBASIC prints it on the console; 
otherwise, a ? is output. In both cases, a blank is then printed and a line of input data is 
read from the console and assigned to the variables as they appear in the variable list. 




The variables can be either simple or subscripted string, or numeric. 

The maximum number of characters that can be entered in response to an INPUT 
statement is 255. If 255 or more characters are entered, inputting automatically ends 
and the first 255 characters are retained. Additional characters are lost. The 255 
characters include all characters entered in response to an INPUT statement, no matter 
how many variables appear in the variable list. 

All CP/M line editing functions, such as CTRL-U and DELETE, are in effect. A 
CTRL-C terminates the program without closing open files. If a CTRL-Z is the first 
character entered in response to an INPUT statement, the program ends in the same 
manner as if a STOP statement was executed. 

The data items entered at the console must be separated by commas and are ended 
by a carriage return. Strings enclosed in quotation marks allow commas and leading 
blanks to be included in the string. 

The prompt string must be a string constant. If it is an expression or a numeric 
constant, an error occurs. 

If the value entered for assignment to an integer is real, the number entered is 
truncated to the integer portion of the real number. If the value of a number assigned 
to an integer variable is outside the range of integers, an incorrect value is assigned. 
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If a real number exceeds the range of CBASIC real numbers, the largest real number 
is assigned to the variable, and a warning is printed on the console. 

If too many or too few data items are entered, a warning is printed on the console, 
and the entire line must be reentered. 

Examples: 

INPUT AM0UNT1 » AM0UNT2 t AM0UNT3 

INPUT "WHAT FILE* PLEASE? " 5 F I LE , NAME* 

INPUT "YOUR PHONE NUMBER PLEASE:"; PHONE. N$ 

INPUT "" 5ZIP.C0DEZ 

A special type of INPUT statement is the INPUT LINE. The general form of this 
statement is: 

INPUT [prompt string ;] 
LINE variable 

Some examples are: 

INPUT "ENTER ADDRESS " 5 L I NE ADDR* 

INPUT "TYPE RETURN TO CONT I NUE " 5 L I NE DUMMY* 

The INPUT LINE statement functions as described above with the following excep- 
tion: only one variable is permitted following the keyword LINE. It must be string. 
Any data entered from the console is accepted and assigned to this variable. The data 
is terminated by a carriage return. 

A null string is accepted by responding to a INPUT LINE statement with a carriage 
return. If the variable specified to receive the input is not string, an error occurs. 

Prompt strings are directed to the console even when a LPRINTER statement is in 
effect (See Section 4.3). 
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INT Function 

INT(x) returns the integer part of the argument x; the fractional part is truncated. 

Syntax: 

y = INT(x) 

Explanation: 

The value returned by INT is a floating-point number. The argument should be 
numeric. If x is an integer, CBASIC converts it to a real number. 

Examples: 

TIME=INT(MINUTES)+INT(SECONDS) 

IF (X/2)-INT<></2)=0 THEN PRINT \ 
"EVEN" ELSE PRINT "ODD" 
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INT% Function 

INT%(x) converts the argument x to an integer value. 

Syntax: 

y% = INT%(x) 

Explanation: 

The argument should be numeric. If x is an integer, it is first converted to a real 
number, and then converted back to an integer. 

Examples: 

SI = INTZ (REC.IMO) 

WIDTH*. = DIMEN,!*, + I NT'*. ( D I MEN . 2 ) 
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LEFTS Function 

LEFTS returns a string consisting of the first i% characters of a$. 

Syntax: 

b$ = LEFT$(a$,i%) 

Explanation: 

If i% is greater than the length of a$, LEFTS returns the entire string. If i% is zero, 
a null string is returned. If i% is negative, a run-time error occurs. 

a$ must be a string; otherwise, an error occurs. i% should be numeric. If i% is real, 
CBASIC converts it to an integer. If i% is a string, an error occurs. 

Examples: 



PRINT LEFT*( INPUT. DATA* ,25) 

IF LEFT*(IN$»1) = "Y" THEN GOSUB 400 
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LEN Function 

LEN returns the length of a$. 
Syntax: 

i% = LEN(a$) 
Explanation: 

If a$ is a null string, LEN returns zero. 

The value returned by LEN is an integer. If the argument is numeric, an error occurs. 

Examples: 

IF LEN(TEMPORARY$) > 25 THEN \ 
TOO ♦LONG! = TRUE* 

FOR INDEX* = 1 TO LEN(OBJECT$) 

NUM*( INDEX*) = ASC(MID$(OBJECT$ * INDEX"/. »1 ) ) 

NEXT INDEX* 
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LET Statement 

The LET statement assigns a value to a variable. 

Syntax: 

[LET] variable = expression 

Explanation: 

The expression is evaluated and assigned to the variable appearing on the left side 
of the = . The variable and expression must both be string or numeric type. 

If the variable and expression are both numeric but one is integer and the other is 
real, an automatic conversion to the type of the variable on the left of the = is 
performed. 

Examples: 

100 LET A = B + C 

X ( 3 , P0 I NTERX ) = 7,32 * Y + X ( 2 * 3 ) 

SALARY = (HOURS, WORKED * RATE) - DEDUCTIONS 

d a t e $ = month* + " " + day* + " » " + year* 

INDEX'/, = INDEX?. + 1 

REC. NUMBER = OFFSET? + NEXTREC'Z 
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LOG Function 

LOG(x) returns the natural logarithm of x. 
Syntax: 

y = LOG(x) 
Explanation: 

The natural or Naperian logarithm of the argument x is the Base e inverse of the EXP 
function. 

The value returned by LOG is real. If x is an integer, CBASIC converts it to a real 
number. 

Examples: 

EASE, TEN, LOG = LOG ( X ) /LOG ( 1 ) 
PRINT "LOG OF )( IS "5 LOG(X) 
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LPRINTER Statement 

LPRINTER sends output to the printer or list device. 

Syntax: 

LPRINTER [WIDTH numeric exp.} 

Explanation: 

After execution of the LPRINTER statement, all PRINT statement output, usually 
directed to the console, is output onto the list device. 

The list device is the physical unit currently assigned to LST: by CP/M. The WIDTH 
clause is optional. If present, the expression is used to set the line width of the list 
device. 

If the console cursor position is not 1, a carriage return and line-feed is output to 
the console. In this context, the cursor position is the value returned by the POS function 
before executing the LPRINTER statement. 

The expression should return an integer. If it is real, the value is rounded to an 
integer. If the expression is string, an error occurs. 

If the WIDTH clause option is not present, the most recently assigned width is used. 
Initially the width is set to 132. A width of results in an infinite line width. With a 
zero width in effect, carriage returns and line-feeds are never automatically output to 
the printer as a result of exceeding the line width. 

Examples: 

500 LPRINTER 

IF HARDCOPY. WANTED*. THEN LPRINTER WIDTH 120 

LPRINTER WIDTH REQUESTED . WIDTH* 



57 



MATCH Function 



MATCH Function 



CBASIC Language Reference Manual 



MATCH returns the position of the first occurrence of a$ in b$ starting with the 
character position given by the third parameter. A zero is returned if no MATCH is 
found. 




Syntax: 

j% = MATCH(a$, b$, i%) 
Explanation: 
The following pattern-matching features are available: 

■ # matches any digit (0-9). 

■ ! matches any upper- or lower-case letter. 

■ ? matches any character. 

■ \ serves as an escape character indicating the following character does not have 
special meaning. For example, a ? signifies any character is a MATCH unless 
preceded by a \. 

a$ and b$ must be strings. If either of these arguments are numeric, an error occurs. 
If i% is real, it is converted to an integer. If i% is a string, an error occurs. If i% is 
negative or zero, a run-time error occurs. When i% is greater than the length of b$, 
zero is returned. If b$ is a null string, a is returned. If b$ is not null, but a$ is null, 
a 1 is returned. 

The following program experiments with the MATCH function: 



n i.t in DSf o f o c; c u rrences is » # # " 

t a r object s t r i n 4 " 5 LINE o b J e c t $ 
t 9 r argument string" 5 LINE ari$ 



N G e cl l t $ 5 occurre n c e "L 
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MATCH Function 



fill 



G20 



rem count occurrences 

location'/, = 1 
occurrence'/, = 
WHILE TRUE'/, 

location'/ = MATCH (arsf$»obJect$»locationI) 
IF location/! 1 , = THEN RETURN 
occurrence! = occurrence'/ + 1 
location! = location'/ + 1 
WEND 



END 



Examples: 

MATCH ( " is" •"Now is t h e " * 1 ) returns 5 

MATCH ("##", "Oct obe r 8, 19 76",!) returns 12 

MATCH* "a?" »" character" »4) returns 5 

MATCH( "\#" ," 123#45" ,1 ) returns a 

MATCH ( "ABCD" ," ABC" ,1 ) returns 

The third example returns a 5 instead of a 3 because the starting position for the 
MATCH is position 4. In example four, the \ causes the # to MATCH only another 
#. Without the \ a 1 is returned. 

The next example is a more complicated statement using the \: 

MATCH ( "\#1\\\?" , " 1«1\?2*" ,1 ) returns 2 
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MID$ Function 

MID$ returns a string consisting of the j% characters of a$ starting at the i% 
character. 

Syntax: 

b$ = MID$(a$,i%,j%) 

Explanation: 

If i% is greater than the length of a$, a null string is returned. If j% is greater than 
the length of a$, all characters from i% to the end of a$ are returned. If either i% or 
j% is negative, an error occurs. If i% is zero, a run-time error occurs. A zero value of 
)% returns a null string. 

a$ must be a string expression; otherwise, an error occurs. i% and j% must be 
numeric. If i% or j% are real, they are converted to integers; if either i% or j% are 
strings, an error occurs. 

Examples: 




DIGIT* = !1ID$(0BJECT$ tPQSl ,1 ) 

DAY$ = MID$( "MONTUEWEDTHUFRISATSUN" »DAYZ*3-2*3) 
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NEXT Statement 
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NEXT Statement 

A NEXT statement denotes the end of the closest unmatched FOR statement. 

Syntax: 

NEXT [identifier ^identifier}] 

Explanation: 

If the optional identifier is present, it must match the index variable of the terminated 
FOR statement. 

The list of identifiers allows terminating multiple FOR statements. The statement 
number of a NEXT statement appears in an ON or GOTO statement, discussed later 
in this section, where execution of the FOR loop continues with the loop variables 
assuming their current values. 

Examples: 

FOR 11 = 1 TO 10 

FOR SI = 1 TO 20 

)<( 11 tJl) = II + JI 
NEXT SI * 11 



FOR LOOP'/, = 1 TO ARRAY, SIZE'*. 

GOSUB 200 

GO SUB 300 
NEXT 
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Examples: 



ON Statement 



ON 



I* GOTO 10, 20, 3, 



ON J% 



1 GO 



SL) B 12.10, 12,2< 



WHILE TRUE*. 

GOSUB 100 

gosub no 



' 12,30, 12.40 



REM ENTER PROCESS DESIRED 

-' -OCESS.OES E M 0™ L T ^/H ST ° 
IF PROCESS. DESIRED* < g THENX ^ 

^PROCESS. OESIREoJcosUB X 
o' v N ADD A ^CORD 

lo-o ' v ALTER NA * E 

I "- U ' \ UPDATE QUANTITY 



NUMBER 



1030, \ 
1040, \ 
1 5 , \ 



DELETE A RECORD 
CHANGE COMPANY CODE 
REM --" L 



WEND 



ELSE GOSUB 400 dcm tr GET PRINT OUT 
UD auo REM ERROR _ ppTpw 



RETR' 




63 



3BHIJ 



OPEN Statement 



OPEN Statement 



CBASIC Language Reference Manual 




The OPEN statement activates an existing file for reading or updating. 

Syntax: 

OPEN "filespec" [RECL rec length]\ 

AS file number [BUFF number of sectors]\ 
RECS size of sectors 

Explanation: 

The first expression represents the filename on disk. The name can contain an 
optional drive reference. If the drive reference is not present, the currently logged drive 
is used. The filename must conform to the CP/M format for unambiguous filenames. 
Lower-case letters used in filenames are converted to upper-case. The expression must 
be string; if it is numeric, an error occurs. The following examples are valid filenames: 

ACCOUNT, MST 

CBAS8G.CMD 

B: INVENTORY. 6 AK 



The third example shows a reference to a file on drive B. 

The directory on the selected drive is searched and the named file is opened. If the 
file is not found in the directory, it is treated as if an end-of-file was encountered during 
a READ. When you specify a drive, it is your responsibility to ensure that the drive is 
available on your system. 

When the optional RECL expression is present, the file consists of fixed length 
records. If the record length is negative or zero, a run-time error occurs. A file is 
accessed randomly or sequentially when a record length is specified; otherwise, only 
sequential access is allowed. The RECL expression must be numeric; real numbers are 
converted to integers. A string value causes an error. 

The AS expression assigns an identification number to the file being opened. This 
value is used in future references to the file. Each active file must have a unique number 
assigned to it. If the expression is not between 1 and 20, a run-time error occurs. The 
expression must be numeric; real numbers are converted to integers. A string value 
causes an error. 
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OPEN Statement 
The BUFF and RECS 

mamtam In memo ry at one time. ° f d ' sk Sectors f ™m the selected file 

If the expression is omitted, a value of n„„ • 
gnoted. The value should be the sizeof a ^^t^^^^^ 

It random access is used with a file the BI IPP 
""*• a run - tlm ^ error occurs. ' BUFF ex P"«,on must evaluate to 1 ; other- 

Both expressions must be numeric- if i, ; 
are converted to mtegers. ""*' «" " * «™S -lue, an error occurs. Real numbers 

Twenty files can be aaj 

Therefore storage space is saved Z opit/f?^ *" fifc * 1S al, °«*d dynamicallv 
«° longer needed. by °P en,n g «« as requmed and closmg [he™ when 

Examples: 

555 0P EN "TRANS. FIL" AS 9 

OPEN FILE. NAME* AS FILE.N07 bi.pp , 

N0/ BU|r F 2B RECS l? 8 

1LE/ BUFF BS% RECS 12B 
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The OUT statement sends the low-order eight bits of the second expression to the 
CPU output port selected by the low-order eight bits of the first expression. 

Syntax: 

OUT i% , j% 

Explanation: 

Both arguments must be numeric; they must be in the range of to 255 for the 
results to be meaningful. If either expression is string, an error occurs. Real values are 
converted to integers before performing an OUT instruction. 

Examples: 

OUT 1 ,58 

OUT FRONT, PANEL*. > RESULT'/. 

IF ;(X > 5 THEN OUT 9, ( ( X*X ) - 1 ♦ ) / 2 ♦ 

OUT TAPE. DR I ME, CONTROL, PORT! » REWIND*. 

OUT PORT*. (SELECTED*. > t ASC("$") 
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PEEK Function 

PEEK returns the contents of the memory location specified by an absolute address. 

Syntax: 

i% = PEEK (numeric exp.) 

Explanation: 

The value returned is an integer ranging from to 255. The memory location must 
be within the address space of youi computer for your results to be meaningful. 

The expression must be numeric. If a string expression is specified, an error occurs. 
Real values are rounded to the nearest integer. 

Examples: 

100 MEM0RY'*, = PEEK( 1 ) 

FOR INDEXI = 1 TO PEEK'*. < BUFFER"*.) 

IN. BUFFER$( INDEX'/. ) = CHR$ ( PEEK'/, ( BUFFER'*. + I NDEX* ) ) 
NEXT INDEX! 
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POKE stores the low-order byte of a specified variable into memory at a specified 
absolute address. 

Syntax: 

POKE numeric exp , j% 

Explanation: 

The first expression must evaluate to an absolute address for your results to be 
meaningful. 

Both expressions must be numeric. If a string expression is specified, an error occurs. 
Real values are rounded to the nearest integer. 

Arguments are passed to machine language subroutines with the PEEK and POKE 
instructions. 

Examples: 

750 POKE 1700 ,ASC( " $ " ) 

FOR LOC'Z = 1 TO LEN(0UT,MSG$) 

POKE MSG.LOCX + LOC'Z. ♦ ASC ( M I D$ ( OUT . MSG$ tLOCl 1 1 ) ) 
NEXT LOCI 
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CBAS1C Language 

POS returns the next posmo n^b< = P^ ^ ^ 
value ranges from 1 to the un 



Explanation: position to be printed 

If cursor control characters 
is not advanced. 

^^ HFftD IS ft T COLUMN: "■■ P°S 

pRINT "THE PRINT HEAD IS 

pn e, <" 15 THEN PRINT 
IF (WIDTH. LINE - P0-> ' 




^;;J??p?T- 
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PRINT Statement 
PRINT Statement 

The PR1N T statement 



outputs the value 
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of each expression to the 
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^UKT expression Mi^^ 

i -u«» lUt device. If 
!3^^2Si t is directed to the Us ^ 

^P^ER ^!tfA ^h^StftA * reached 

^ir: the -matndet of the strmg, u any, ^ 

and then comma or a sen " , f his spa cing 

onto the next line, a 

t whose list does not end m e.ther 
. Another PRINT^^'^ 05 

C T t toe wiSt exce^ t ., executed . 

A LPWNTER or CON* statero ent. 

The program executes a 

_„:~« Ust ca 



■ A LPRlNlfc* a STOP statement. 

I ^he program executes a ^ ^ ^ . Une , ee d 

A PR.NT statement^ no expressronhstc 
X ^ mls endedduetoanerror,acarrrageretumandahne,ed 

lfe xecu«on of a program .send 
are output. 
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PRINT Statement 




Examples: 

PRINT AMOUNT, PAID 

PRINT QUANTITY* PRICE* QUANTITY * PRICE 

PRINT "TODAY'S DATE IS: ";MONTH$?" "5DAY/f, i" "5YEARI 
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PRINT # Statement 

The PRINT # statement outputs data to a disk file. 

Syntax: 

PRINT # filespec,[rec spec] ;variable{,variable} 

Explanation: 

Data is written to the file designated by the filespec. You can specify a particular 
number in the rec spec for files with a fixed record length only. Otherwise, data is 
written sequentially. Refer to Section 5 for more information on file input and output. 

Examples: 

PRINT*CLIST.STO ?A$B$C$ 
PRINT«2 »3 ?GZ tHZ tl t Jl >K 
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PRINT USING Statement 

PRINT USING allows formatting of printed output using a format string. PRINT 
USING # sends formatted data to a disk file. 

Syntax: 

PRINT USING [#] format string; 
[filespec] expression list 

Explanation: 

A format string is composed of data fields and literal data. Data fields are numeric 
or string. Any character in the format string, that is not part of a data field is a literal 
character. 

A format string can be any string expression. This allows the format to be determined 
during program execution. If the format string is numeric, an error occurs. If the 
expression evaluates to a null string, a run-time error occurs. 

The expression list consists of expressions separated by commas or semicolons. The 
comma does not cause automatic tabbing as it does with the unformatted print. Each 
expression in the list is matched with a data field in the format string. If there are more 
expressions than fields in the format string, the format string is reused starting at the 
beginning of the string. 

While searching the format string for a data field, the type of the next expression 
in the list, either string or numeric, determines which data field is used. For example 
if a numeric data field is encountered while outputting a string, the characters in the 
numeric data field are treated as literal data. An error occurs if there is no data field 
in the format string of the type required. 

A PRINT USING statement without the file reference causes an output line to be 
written to the console or the line printer. The console is selected unless a LPRINTER 
statement is in effect. If the file reference is present, the line is composed as if the output 
is printed on a list device. The entire line is then written as a record in the selected 
file. Refer to Section 5 for more information. 
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The RANDOMIZE statement initializes or seeds the random number generator. 

Syntax: 

RANDOMIZE 

Explanation: 

Operator time taken to respond to an INPUT statement is used to set the seed 
(see Section 4.2). This time varies with each execution of a program. Therefore, for 
RANDOMIZE to work correctly, it must be preceded by an INPUT statement. 

Examples: 

450 RANDOMIZE 
RANDOMIZE 
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READ Statement 



The READ statement assigns items listed in a DATA statement sequentially to the 
variables listed in the READ statement. 



Syntax: 

READvariable,{variable} 

Explanation: 

READ statements can contain mixed DATA types as long as each type corresponds 
positionally to each type listed in the DATA statement. See DATA statement for more 
information. 

Examples: 



READ A'*, , BZ , CI 

DATA 14 , 25B > 73 

READ A$ , B7, » C 

DATA "Friday's 25 t a ♦ 
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READ # Statement 

The READ # statement reads secme ntially from the <*^^«?^ 

sion. The file i, read, ^^^^^^ 

a value. Fields are integer, floating point, or string 



Syntax: 



READ # expression ; variable 
{, variable} 



Explanation: 

~, r c Ap RF AD # statement that access data from disk files. Each 

There are four forms of * e ^ t ^^ neral comme nts follow about reading from 
of the four statements are discussed then gene files simllar to usl ng 

disk files. The first two types of ^^*^^ e la8t two forms are similar 
the INPUT statement to access data from the console, 
to the INPUT LINE statement. 

Th e expression, which selects ^^J^T^ - ^S 
to integer. A string value causes an error. Also, me 
otherwise, a run-time error occurs. 

A variation of the READ # statement takes the general form: 

READ # expression , ^ssionj^ ^ ^.^ 
The fo.low.ng i. an example of th.s variation of the READ # statement: 

, paD , FILE.N07.,REC. COUNT!! NAME*. PAY, HOURS, X 

TERM. OF. EMPLOY »SSN$ 

Tbe second expression selects *« -^"^ J^S^SM 
the second expression is read f -™ *%^ a btmh variable list. If there are more 
fields in the record are assigned to ^J*™°™" form of READ #> the 

variables than fields m the record an error on * ^ 
file must be activated with the RECL option specified. 
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READ # Statement 




The second expression must be numeric. If the value is a string, an error occurs. 
Real values are converted to integers. The record number cannot be zero; if it is, a 
run-time error occurs. The expression is treated as a 16-bit unsigned binary number. 
This allows record numbers to range from 1 to 65,535. 

A random READ #, with no variables specified, positions the file to the selected 
record. A subsequent sequential READ # accesses the selected record. 

The following two forms of the READ # statement treat files as lines of text. The 
sequential variant takes the general form: 

READ # expression ; LINE variable 

This statement sequentially reads all data from the specified file until it encounters 
a carriage return followed by a line-feed. All the data read up to, but not including, 
the carriage return and line-feed is assigned to the single string variable specified in 
the READ LINE statement. If the variable is not string, an error occurs. 

The random variant of the READ LINE has the following general form: 

READ # expression , expression ; 
LINE variable 




Some examples are: 

READ * 12 5 LINE NEXT . LINE . OF . TEXT$ 

READ # INPUT. FILE'*. ♦ RECORD"*. 5 LINE NEXT*ONE$ 

The final variation reads the record specified by the expression, from the file specified 
by the first expression. The data is assigned to the string variable as described for the 
previous form of the READ LINE statement. 

The READ LINE statement permits CBASIC to access records containing ASCII data 
in any format on a line-by-line basis. For example, any file created using text editor 
can be read a line at a time. In the following example, 

READ * 125 LINE in*strinS$ 

all characters in the next record are read until a carriage return followed by a line- 
feed is encountered. 
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READ # Statement 

Examples: 

READ * 7? STRING*, NUMBER 

READ * FILE ♦MASTER'*.! NAME*, ADDRESS* »C I TY* t ST ATE* 
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REM Statement 

The REM statement documents a program. 
Syntax: 

REM [string terminated with CR] 

REMARK [string terminated with CR] 

Explanation: 

REM statements do not affect the size of the program compiled or executed. When 
the Compiler ignores a REM statement, compilation continues with the statement 
following the next carriage return. A continuation character causes the next line to be 
part of the remark. An unlabeled REM statement can follow any statement on the 
same line. The statement number of a remark can be used in a GOSUB, GOTO, IF, 
or ON statement. 

Examples: 

REM THIS IS A REMARK 

remark this is also a remark 

TAX = 0,15 * INCOME REM LOWEST TAX RATE REM \ 
THIS SECTION CONTAINS THE \ 
TAX TABLES FOR CALIFORNIA 

The last example shows a REM statement on the same line with another statement. 
When using the REM statement in this manner, the colon is optional between the two 
statements. In all other cases involving multiple statements on the same line, the colon 
must separate the statements. If the REM statement is used on the same line with other 
statements, it must be the last statement on the line. All statements after a REM are 
ignored. 
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RENAME Function 

RENAME Function b$ to he nam e 

gl ven by a$. Renammg a We 

Syntax: 

i0/o = R£NAME(a$,b$) 

^^ a n integer vaiue. A true (-« "ned ^ t 

The RENAME ^j-rnie" $"£ returned when the RENAM 
RENAME is successtul, a exist 

Lmpk, false -turned^ ^^ when CBAMC a— ^ 

m b$ is numenc , a „ error occur, 
Both atgutnents must ^ ^ ^ ^^ ^ conventIon: 

The RENAME function allows you ^ ^ 

ci, i, opened w.th a filetype of $$$,'"* » a Wetype BAK, is 
The output Ue is °P^ e fi , ename as the output file, 
\ Any file wtth the same We _ tocess ed. 

deletei • to the temporary hk as the program 'sp ^.^ 
, Data is written to the temp tenames any hew BAK 

I ^^rn^» te, ^^XtU- ^name and 
5 . The S^rrenames the temporary output 
filetype. 

E-fe , M . T „ ...PAYROLL.***"' 

MV , - RENAME (" PAYROLL. MST 

n,OFILE*> THEN RETURN 
IF R ENA M E(NE W FILE*,OLDFILE* 
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RESTORE Statement 

A RESTORE stamen. aHows reread of the constants contatned ,n DATA state- 



ments. 



Syntax: 

RESTORE 

Explanation: . , 

" • • uMTA statement pointer to the beginning ot 

A RESTORE statement repositions the UAi as JN statem ent is 

the DATA area. A RESTORE statement is executed whe 
present. 
Examples: 
500 RESTORE 
IF END. OF. DATA! THEN RESTORE 



t: 
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RETURN Statement 

The RETURN statement sends control from a subroutine back to the main program. 

Syntax: 

RETURN 

Explanation: 

The RETURN statement causes the execution of a program to continue at the location 
on top of the return stack. The call might be a GOSUB statement, an ON. . .GOSUB 
statement, or a multiple-line function call. (See Section 4.2.2 for a discussion of multiple- 
line functions.) 

If a return is executed without previously executing a GOSUB, ON... GOSUB, or 
multiple-line function call, a run-time error occurs. 

Examples: 

500 RETURN 

IF ANSWER ♦VALID"*. THEN RETURN 
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RIGHTS Function 

RIGHTS returns a string consisting of the i% rightmost characters of a$. 

Syntax: 

b$ = RIGHT$(a$,i%) 

Explanation: 

If i% is negative, a run-time error occurs. If i% is greater than the length of a$, the 
entire string is returned. If i% is zero, a null string is returned. 

a$ must evaluate to a string; otherwise, an error occurs. i% must be numeric. If i% 
is real, it is converted to an integer. If i% is a string, an error occurs. 

Examples: 

IF RIGHT$( ACCOUNT, NQ$ ,1 ) = "0" THEN \ 
TITLE, ACCT/f; = TRUE'/, 

NAME* = RIGHT$(NAME$ » LEN ( N AME$ ) - LEN ( F I RST . NAMES) ) 
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RND generates a uniformly distributed random number between and 1. The value 
returned by RND is a real number. 

Syntax: 




x = RND 

Explanation: 

To avoid identical sequences of random numbers each time a program is executed, 
the RANDOMIZE statement is used to seed the random number generator. 

Examples: 

DIE'Z=INT'£(RND*G. ) + l 

IF RND > ,5 THEN \ 

HEADS'* = TRUE'*. \ 
ELSE \ 

TAILS'/. = TRUE"* 



IV- :■ ■•; '■'•• V"'; 

>■■■■••,■"■. ■-:■.■=; 
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SADD Function 

SADD returns the address of the string assigned to the argument a$. 

Syntax: 

i% = SADD$(a$) 
Expla nation: 

The first byte is the length of the string followed by the characters in the string. The 
length is stored as an unsigned binary integer. Therefore, if the string is TOTAL, the 
SADD function returns the address of a byte containing a binary 5. 

The value returned by SADD is an integer. If a$ is not a string, an error occurs. 
When the parameter evaluates to a null string, a zero is returned. 

The SADD function, with PEEK and POKE, passes a string to an assembly language 
routine for processing. 

Examples: 

The following statements place the address of STRINGS into the address stored in 
PARM.LOC%: 

POKE PARM.LOCTf. »SADD(STRING$) AND OFFH 
POKE PARM.LOC'X+1 ,SADD ( STRING* ) /25B 




I 
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The SAVEMEM statement reserves space for a machine language subroutine and 
loads the specified file during execution. Only one SAVEMEM statement can appear 
in a program. 




Syntax: 

SAVEMEM constant , filespec 

Explanation: 

The constant must be an unsigned integer specifying the number of bytes of space 
to reserve for machine language subroutines. The space is reserved in the highest address 
space of the CP/M Transient Program Area. The beginning address of the reserved 
area is calculated by taking the constant specified in the SAVEMEM statement and 
subtracting it from the 16-bit address stored by CP/M at absolute address 6 and 7. 
However, for the 8086 version of CBASIC, the load address is rounded down to the 
nearest 16-byte paragraph boundary. 

The expression must be string, and can specify any valid unambiguous filename. 
The selected file is loaded into memory starting with the address calculated above. 
Records are read from the file until either an end-of-file is encountered, or the next 
record to be read overwrites a location above the Transient Program Area. 

If the constant specifies less than 128 bytes to be saved, nothing is read, but the 
space is still reserved. If the expression is a null string, space is saved but no file is 
loaded. 



If a main program has a SAVEMEM statement, any chained program having a 
SAVEMEM statement must reserve the same amount of space. Each chained program 
loads a new machine language file or uses the file loaded by a previous program. The 
space reserved by the main program is not reclaimed by a subsequent program. 

It is your responsibility to ensure the machine language routines are assembled to 
execute at the proper address. Also, the location where a program is loaded depends 
on the size of the CP/M system used. 

The CALL statement accesses routines loaded by SAVEMEM. The CALL statement 
loads the data, code, and extra segment registers to the base of the SAVEMEM area. 
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Examples: 

SAVEMEM 25G » " SEARCH ♦ CMD " 

SAVEMEM 512, DR$+ "CHECK," + ASSY$ ( FN . CPM . S I ZE7, ) 
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SGN Function 

SGN (x) returns an integer value representing the algebraic sign of the argument. 

Syntax: 

i% = SGN(numeric exp) 

Explana tion: 

Tc^N returns a -1 if * is negative, a if x is zero, and a + 1 if x is greater than zero. 

x can be integer or real. Integer values of x are converted to real numbers. The 
argument should be numeric. SGN always returns an integer. 

Examples: 

IF SGN(BALANCE) <> THEN \ 
OUTSTANDINGBAL'X. = TRUE*. 

IF SGN(BALANCE) = -1 THEN \ 
OVERDRAWN'*. = TRUE'*. 
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SIN Function 

SIN(x) returns the sine of x. 
Syntax: 

y = SIN(x) 
Explanation: 

The argument x is expressed in radians. The value returned by SIN is real. If x is 
an integer, it is converted to a real number. 

Examples: 

FACTOR(Z) = SIN(A - B/C) 

IF BIN (ANGLE/ (2.0 * PI)) = 0,0 THEN \ 
PRINT "HORIZONTAL" 
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SIZE Function 

SIZE returns the size in 1 kilobyte blocks of the file specified by a$. 
Syntax: 

i% = SIZE(a$) 

Explanation: 

If the file is empty or does not exist, zero is returned. a$ is any CP/M ambiguous 
filename. 

The argument must be a string expression. If the argument is numeric, an error 
occurs. The SIZE function returns an integer. 

The SIZE function returns the number of blocks of disk space used by the file or 
files referred to by the argument. When the operating system allocates disk space to a 
file, it does so in one block increments. A file of 1 character occupies a full block of 
space. This means the SIZE function returns the amount of space reserved by the file 
rather than the size of the data in the file. 

This function is useful in a program that duplicates or constructs a file on disk. If 
the program creates a file of a given size, dependent on the size of its input file, it first 
determines whether or not there is sufficient free space on the disk before building the 
new file. 

Consider a program that reads a file named INPUT from drive A, processes the data, 
and then writes a file named OUTPUT to drive B. Assume the size of OUTPUT is 
125% of INPUT. The following routine ensures space is available on disk B before 
processing: 

rem test for enough room 

s l ze . of , output'/, = 1,25 * s i z e ( " A : I NPUT " ) 

f ree.blocksl = 2 41 - si:e( "B:*,#" ) 

if free. space'/, < s i z e » o f ♦ o u t p u t 7, t h e n \ 

snoijSh. rooiii'Z = F A L S E 7, \ 

else e r< a u 3 h . r o o m 7, = TRUE'/, 
ret u r n 
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Examples: 

BIZE( "NAMES. BAK" ) 

SIZE(COMPANY$ + DEPT$ + "♦NEW") 

SIZE( "B:ST?RTR?K\*" ) 

S I ZE ("*,*" ) 

SIZE( "*,BAS'* ) 



SIZE Function 



■H" 
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SQR Function 

SQR (x) returns the square root of the argument x. 

Syntax: 

y = SQR(x) 

Explanation: 

If x is negative, a warning message is printed and the square root of the absolute 
value of the argument is returned. 

The value returned by SQR is real. If x is an integer, it is converted to a real number. 

Examples: 

HYPOT = SOR( (SIDE 1 A 2 , > + ( S I DE2 -2,0) ) 

PRINT USING \ 

"THE SQR ROOT OF X IS: #***.#«•'; SQR(X) 
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STR$ Function 

STR$ (x) returns the character string representing a numeric value specified by x. 
Syntax: 

a$ = STR$(x) 
Explanation: 

If x is a string, an error occurs. 
Examples: 

PRINT STR$(NUMBER) 

IF LEN(STR$( VALUE) ) >5 THEN ED$= "###«##« " 
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TAB Function 



TAB causes the cursor or list device print head to be positioned at a location specified 
by the value of the expression. The TAB function is only used in PRINT statements. 

Syntax: 

TAB (numeric exp) 

Explanation: 

If the value of the expression is less than or equal to the current print position, a 
carriage return and line-feed are output then TAB is executed. 

The TAB predefined function is implemented by outputting blank characters until 
the desired position is reached. If cursor or printer control characters are output, the 
cursor or print head might be positioned incorrectly. 

The expression must be numeric. If a string expression is specified, an error occurs. 
If the expression is real, it is first rounded to an integer. An error occurs if the expression 
is greater than the current line width. 

Examples: 

PRINT TA3( 15) ? "X" 

PRINT "THIS IS COL. 1 " 5 TAB ( 50 ) 5 " TH I S IS COL. 50" 
PRINT TABOa. + YX/ZX) ! " ! " 5 T AB ( POS'Z + OFFSETZ ) 5 
PRINT TAB(LEN(STR$(NUMBER) ) ) 5"*" 
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TAN Function 

TAN (x) returns the tangent of the argument x. 

Syn tax: 

y = TAN(x) 

Explanation^ 

The argument x i. expressed m rad.an. The value returned by TAN i. real. If x i. 
an integer, it is converted to a real number. 

Examples: 

POWER. FACTOR = TAN ( PHASE ♦ ANGLE ) 

QUIRK = TAIMCX - 3.0 * COS(Y)) 
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VAL Function 

VAL Function 

VAL converts a numeric 

Syntax: 

v = VAL(a$) 
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VARPTR Function 

VARPTR returns the storage location assigned to the variable by the run-time mon- 

Syntax: 

i% = VARPTR {variable) 
Explan ation: 

With an unsubscripted numeric quantity, this is the actual location of the variable 
in question. For string variables, the value returned by VARPTR is the address of a 
16-bit pointer to the referenced string. Because strings are dynamically allocated the 
actual location of the string varies, but the value returned by VARPTR remains unchanged 

vT^xr 8 " 3 " 1 CXeC T on - If the variable « ^ common, the location returned by 
VAKPIR remains unchanged after chaining. 

If the variable is subscripted, the value returned by VARPTR is the address of a 
pointer to the array dope vector in the free storage area. The array follows the dope 
vector The first byte of the dope vector is the number of dimensions followed by n- 
1, n is the number of dimensions, 16-bit offsets into the array. The final 16-bit quantity 
in the dope vector is the number of entries in the array. The array follows in row- 
major order. 
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WEND Statement 

A WEND statement denotes the end of the closest unmatched WHILE statement. 
Syntax: 

WEND 
Explanation: 

A WEND statement must be present for each WHILE statement in a program. 

Branching to a WEND statement is the same as branching to its corresponding 
WHILE statement. 

Examples: 

WHILE -1 

PRINT "X" 
WEND 




WHILE 



38 



PRINT 



/\ — /\ 



WEND 

TIME = 0,0 

TIME .EXPIRED/!: = FALSE! 

WHILE TIME < LIMIT 

TIME = TIME + 1.0 

IF CONSTAT! THEN \ 

RETURN REM ANSWERED IN TIME 
WEND 

TIME. EX PI RED! = TRUE! 
RETURN 

WHILE ACCOUNT. IS. ACTIUE! 

GOSUB 100 REM ACCUMULATE INTEREST 
WEND 
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WHILE FILE. EXISTS*. 
WHILE TRUE*. 

IF ARG$ = ACCT$ THEN \ 

ACTIVITY* = TRUE'*. :\ 
RETURN 
IF ARG$ < ACCT$ THEN \ 

ACTIVITY'*. = FALSE! :\ 
RETURN 
GDSUB 3000 REM READ ACCT$ REC 
WEND 
WEND 

ACTIVITY* = FALSE* 
RETURN 



WEND Statement 



pg 



WHILE TRUE*. 

INPUT LINE STRING$ 
IF STRING* = CONTINUE* THEN RETURN 
WEND 
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WHILE Statement 

The WHILE statement loops program control until the specified expression evaluates 
to zero. 

Syntax: 

WHILE expression 

Expl anation: 

XY/pxm tl0n ° f aH j tatei ? ents between the WHILE statement and its corresponding 
WEND are repeated until the value of the expression, in the WHILE section, is zero 
It the value is zero initially, the statements between the WHILE and WEND are not 
executed. Variables used in the WHILE expression can change during execution of the 

The expression should be integer. This reduces execution time and also reduces the 
intermediate code generated by the Compiler. If the expression is real, the value is 
rounded and converted to an integer. A string expression results in an error. 

End of Section 3 
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Section 4 
Defining and Using Functions 



Functions are useful when the same routine or computation is needed in a number 
of locations in a program. Once defined, a function can be referenced or called any 
number of times in the program. 

All CBASIC functions return a value. Any routine that results in a value, either string 
or numeric, can be defined as a function. Functions can pass values and parameters 
for use at each invocation. 



4.1 Function Names 

Function names are defined with the letters FN followed by any combination of 
numbers, letters, or periods. Any number of characters can be used in a function name; 
however, only the first 31 characters, including the FN, distinguish one name from 
another. A function name cannot contain spaces. 

The type of function name determines the type of value that the function passes 
back to the main program. 

■ Names for string functions end with $. 

■ Names for integer functions end with %. 

■ Names for real number functions do not end with $ or %. 

You must use a function name to define a function and to reference a function from 
another location in a program. The following examples are valid function names: 

FN, PROPER, FUNCTION, NAMES 

FN, TRUNCATE* 

FN51234X 



1 

Hi 
HI 
m 



IS- 

It: 



U-- 
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A function definition must occur in a program before making a function reference. To 
define a function, the keyword DEF must precede the function name. CBASIC supports 
two types of function definitions: single-statement and multiple-statement. 



E^.'.'^**; ■*?%-£■'' '3 







4.2.1 Single-Statement Functions 

Single-statement function definitions use an equal sign followed by an expression. 
The expression contains the actual process that the single-statement function is coded 
to perform. The data types used in the expression must correspond to the data type 
used in the function name. Use the following format when defining single-statement 
functions: 

DEF FN function. name [(dummy arg list)] = expression 

A dummy argument holds a place for a variable that is specified in a function 
reference. A dummy argument is either a string variable or a numeric variable; it is 
never a constant. The dummy argument must have the same data type as the variable 
used in the function reference. However, the data type for the dummy argument is 
independent of the function name type. CBASIC considers dummy arguments local to 
the function. Local variables are independent of the rest of a program. CBASIC param- 
eters are passed by value. 

The following examples show single-statement function definitions: 



DEF FN25 = RND * 25.0 

100 DEF FN.HYPOKSIDEl ,SIDE2)= \ 

SQRUSIDE1 * SIDED + (SIDE2 * SIDE2)) 

DEF FN. LEFT. JUSTIFY$(At »LENX ) =LEFT$ ( A* + BLIMKS$ »LENX) 
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4.2 Function Definitions 



4.2.2 Multiple-Statement Functions 

Multiple-statement function definitions use a series of CBASIC statements preceded 
by a DEF statement and terminated with a FEND statement. Also, a RETURN statement 
is placed at some point in the body of the function. The RETURN statement ends 
function execution and sends control back to the main program. Use any number of 
RETURN statements, but be sure a FEND statement is the last statement that appears 
in a multiple-statement function. Use the following format when defining multiple - 
statement functions: 



DEF FN function. name [(dummy arg list)] 
CBASIC Statements 



RETURN 
FEND 



The following two examples show multiple-statement function definitions: 




DEF FN.READ.INPUT( INPUT. NO*) 

READ * INPUT. NO* 5 CUSTNO* , AMOUNT 

RETURN 
FEND 
200 DEF FN. COUNT* ( INDEX 17, ) 

COUNT* = 

FOR I* = 1 TO INDEX1* 

COUNT* = COUNT* + ARRAY (I*) 

NEXT I* 

FN. COUNT* = COUNT* 

RETURN 
FEND 

The following rules apply to multiple-statement functions: 

■ DEF and COMMON statements cannot appear in a function definition. 

■ GOTO statements that reference a line outside of the function are not allowed. 

■ The DIM statement allocates a new array upon each execution of a function. 
Data stored in an array from a previous execution is lost. Arrays in multiple- 
statement functions are global to an entire program. 

■ Functions cannot be nested. However, a function can be called from within 
another function. 
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User-defined functions can be referenced in any CBASIC statement or expression. 
Be sure to specify the same number of parameters in the function reference that are 
specified in the function definition. The function substitutes the current value of each 
expression in the reference statement for the dummy argument in the function defi- 
nition. The following are examples of function references: 

300 PRINT FN.A(FN.B(X) ) 

IF FN, LEN'K "INPUT DATA">X$,Q) < LIMIT*. THEN 
G0SU6 3000 

WHILE FN.ALTITUDE(CURR.ALTX) > MINIMUM. SAFE 

CURR . ALT/f.= I NP ( ALT . PORT*, ) 
WEND 



End of Section 4 
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Section 5 
Input and Output 



CBASIC uses the operating system to control input and output for interaction between 
programs, terminals or console devices, printers, and disk drives. 



5.1 Console Input and Output 

CBASIC reads input from the console one line at a time instead of one character at 
a time. Therefore, all CP/M line-editing functions, such as CTRL-U and DELETE, 
remain in effect. CTRL-C entered from the keyboard terminates a program but does 
not close files being accessed. CTRL-Z entered in response to an INPUT statement 
terminates program execution like a STOP statement. The following statements and 
predefined functions are used to input data from a console device. Refer to Section 3 
for more detailed descriptions of statements and functions. 

■ INPUT statements query the user for information during program execution. 
Any number of input values can be entered with an INPUT statement. A prompt 
message can be displayed if desired. 

■ INPUT LINE works like an INPUT statement, but accepts only one variable 
for data to be entered. All characters entered in response to INPUT LINE are 
interpreted as one string. 

■ READ statements assign values from DATA statements to specified variables. 

■ DATA statements define a list of string, real, and integer constants assigned to 
variables by a READ statement. 

■ RESTORE statements prepare the list of constants in a DATA statement to be 
reread by repositioning a pointer to the beginning of the list. 

■ CONSTAT% is a predefined function that determines console status. The func- 
tion returns a logical true value (-1) if a character is ready at the console, and 
a logical false value (0) if a character is not ready. 

■ CONCHAR% is a function that waits for an entry from the keyboard and 
returns an eight-bit ASCII representation of the character entered. Only printing 
characters can be used with CONCHAR%. 

■ INP is a function that returns an integer value from a specified input/output 
port. 
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The following CBASIC statements and predefined functions control console output. 

■ The CONSOLE statement restores printed output to the console device. 

■ The predefined function TAB moves the console cursor to a specified position 
on the screen. TAB also works with printers. 

■ The POS predefined function returns the next available position on the console 
screen to be printed. 




5.2 Printing 
CBASIC provides two statements to control output to a line printer device. 

■ LPRINTER directs all PRINT statement output to the line printer or list device. 

■ PRINT USING allows formatting of printed output. 



5.3 Formatted Printing 

The PRINT USING statement allows you to specify special formats for output data. 
Formatted data is directed to the console or line printer. The PRINT USING # variation 
directs formatted output to a disk file. A PRINT USING statement is written as follows. 

PRINT USING format string [file number) expression list 

The format string is a model for the output. A format string contains data fields and 
literal data. Data fields can be numeric- or string-based. Any character in the format 
string that is not part of a data field is a literal character. Format strings must be 
nonnull string expressions. The following characters have special meanings in format 
strings: 



& 



# 



single-character string field 
variable-length string field 
fixed-length string field delimiter 
numeric field 

asterisk fill in numeric field 
puts $ in numeric field 
exponential format 
escape character 
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For example, 

FORI* = "THE PART REQUIRED IS / ♦ ♦ , 5 . . . . . . . ♦ 5/ 
PART.DESCRP* = "GLOBE VALUE ♦ ANGLE" 
PRINT USING FORI*? PART.DESCRP* 




outputs: 

THE PART REQUIRED IS GLOBE VALUE ♦ ANG 

Using periods and numbers between the slashes makes it easy to verify that data 
field is 16 characters long. Periods and numbers do not effect the output. 



5.3.3 Variable-Length String Fields 

A variable-length string field is specified with an ampersand, 8>c. This results in a 
string output exactly as defined. 

For example, 

COMPANY* = "SMITH INC*" 

PRINT USING "& : &:" i "THIS REPORT IS FOR" ♦COMPANY* 



outputs: 

THIS REPORT IS FOR SMITH INC* 

A string can be right-justified in a fixed field using the variable string field. The 
following routine shows how this is done. 

FLD*S'£ = 20 

BLK* = " 

PHONE* = "408-649-3896" 

PRINT USING "«&:"; RIGHT*(BLK* + PHONE** FLD.S'X.) 



outputs: 



408-G49-389G 



In the preceding example, because the print list contains only a string expression, 
the # is used as a literal character. A # can also indicate a numeric data field. 
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5.3.4 Numeric Data Fields 



5.3 Formatted Printing 



A numeric data field is specified by a # to indicate each digit required in the resulting 
number. One decimal point can also be included in the field. Values are rounded to 
fit the data field. Leading zeros are replaced with blanks. When the number is negative, 
a minus sign is printed to the left of the most significant digit. A single zero is printed 
on the left of the decimal point if the number is less than 1, and a position is provided 
in the data field. 



The following example illustrates the use of numeric data fields: 

X = 123.754G 

Y = -21. 

FOR$ = "###»»#### ###,# ###" 

PRINT USING FDR$; X > X t X 

PRINT USING F0R$; Y > Y , Y 

Execution of the above program produces the following printout: 

123,7546 123.8 124 
- 2 1 .0 -21.0 - 2 1 

Numbers are printed in exponential format by appending one or more up 
arrows, A , to the end of the numeric data field. 

For example, the following program segment, 

X = 12.345 

PRINT USING "#,#«#-- "5 >(, -)< 

outputs: 

1 . 235E 01 - . 123E 02 

The exponent is adjusted so all positions that the up arrow represents are used. 
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5.3 Formatted Printing 

For example, 

PRINT USING »««*.««' ""' 17.987 

results in: 
179.B7E-01 

Fou r positions are rested for the exponent recess of the number of up arrows 
used in the field. 

„ m UoAArc\ within a numeric data field, the number 

For example, 

.. ^ 4»*« " ; too. iooo* ioooo 

PRINT USING "*# >*** ' 1UU ' 




prints: 



1 



1 >000 



1 » 



• u a«** (M is included in the width of the field. Thus, 
E-h comma appeann gl n the da "^^^ in the output , lt .dearer 

Satc^r : t he dr«e,d in the positions of appearance on the output. 

digits are output: 

^ ™^ a <: are not Drinted; when commas occur in the 
If the exponent option is used, commas are not prime , 

field, they are treated as #. 

Aster.sk fill of a numeric data field is accomplish £ biding two ^ the 
beginning of the data field. A^ ,' ^Ser > fill or the floating 
in a similar manner Exponential o matj not ^ ions available for the field 

i££t « if K iTsS" spaceUhe number and • or ,. The S 
is suppressed if the value printed is negative. 
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For example, 

COST = 8742937.56 

PRINT USING "#*##,###«##,#** 

PRINT USING "$$»#,######♦## 



5.3 Formatted Printing 



; COST f -COST 
; COST , -COST 



prints: 

**B ,742 ,937*56 
$8 ,742 ,937. 56 



*-8 ,742 ,937.56 
-8 ,742 ,937.56 



A number is output with a trailing sign instead of the leading sign if the last character 
in the data field is a minus sign. When the number is positive, a blank replaces the 
minus sign in the printed result. 



For example, 

PRINT USING 



### - n # # •'• 



10, 10, -10, - 1 



outputs: 

10 100E-01 



10- 1 E - 1 



If a minus sign is the first character in a numeric data field, the sign position is fixed 
as the next output position. When the number printed is positive, a blank is output; 
otherwise, a minus sign is printed. 

The following example demonstrates this feature. 

PRINT USING "-**«# "5 10, -10 



outputs: 

10 



10 




Anytime a number does not fit within a numeric data field without truncating digits 
before the decimal point, a % is printed, followed by the number in the standard 
format. 
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For example, 

X = 13 2,71 

PRINT USING "##♦# 
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# # * t * " ; X t X 



outputs: 

1 132,71 132.7 

5.3.5 Escape Characters 

At times you might want to include a character as literal data which, following the 
above rules, is part of a data field. This is accomplished by escaping the character. A 
\ preceding any character causes the next character after the \ to be treated as a literal 
character. This allows, for example, a # to precede a number, as shown in the following 
example. 

ITEM. NUMBER = 31 

PRINT USING "THE ITEM NUMBER IS \###"i ITEM, NUMBER 

outputs: 

THE ITEM NUMBER IS *31 

An escape character following an escape character causes a backslash to be output as 
a literal character. If an escape character is the last character in a format string, a run- 
time error occurs. 



5.4 File Organization 

CBASIC organizes information on a disk surface into three levels: files, records and 
fields. 

■ FILES consist of one or more records. 

■ RECORDS are groups of fields. Each record is delimited by a carriage return 
and line feed. 

■ FIELDS are the individual data items. Each field within a record is delimited 
by a comma. 

CBASIC supports two types of data files on disk: sequential and relative. 
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5.4.1 Sequential Files 



5.4 File Organization 



Sequential or stream organization is performed on a strict field-by-field basis. The 
PRINT # statement writes each field to the disk in a continuous stream. Each data 
item uses only as much space as needed. Each PRINT # statement executed creates a 
single record. Each variable used in the PRINT # statement creates a single field. 
Individual record lengths vary according to the amount of space occupied by the fields. 
There is no padding of data space. The following diagram shows a sequential file 
composed of three records. 



FILE.l 



RECORD 1 


"FIELD ONE'V'FIELD TWO'Y'FIELD THREE"cr/lf 


RECORD 2 


"Field l","Field2",""cr/lf 




RECORD 3 


lll,222,3.3,444,5.5cr/lf 




vary ► 




■M Record lengtr 


is 



Figure 5-1. Sequential File 



Field three in record two is a null string. Commas serve as delimiters, but are 
considered string characters when embedded in a pair of quotation marks. Quotation 
marks are also considered string characters when embedded in a pair of quotation 
marks. 
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The following CBASIC program creates the sequential file diagrammed above. 



CREATE 



FILE* 1 



PR I 
PR I 
PR I 
CLO 
END 



NT 
NT 
NT 
SE 



A$ 

5$ 

C$ 

D$ 

E$ 

F$ 

GX 

HI 

I 

SI 

K 

#1 ; 

#1 5 
*i ? 
l 



FIELD 
FIELD 
FIELD 
FIELD 
FIELD 



AS 1 
ONE" 
TWO" 
THREE" 
1" 



= 111 

_ TOO 

= 3,3 

= aaa 



= 5 
A$ t 
D$ , 
GX , 



5 

B* 
E$ 
HI 



C$ 
F$ 

I t 




SI t K 



The three PRINT statements correspond to the three records and each variable 
corresponds to a field. 

When sequential files are accessed, each field is read consecutively one at a time 
from the first to the last. The READ # statement considers a field complete when it 
encounters a comma or a carriage return and line-feed. The following program reads 
the fields in FILE.l sequentially and prints them on the console screen. 

IF END #19 THEN 100 
OPEN "FILE.1" AS 19 
FOR 17. = 1 TO 11 
READ #19; FIELDS* 
PRINT FIELDS* 
NEXT 11 
100 END 



Any type of variable can be used in the READ # statement in a sequential access. 
Executing the preceding program outputs the following display on the screen. 



FIELD ONE 
FIELD TWO 
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FIELD THREE 
FIELD 1 
FIELD 2 

111 

inn 

3,3 

5 ♦ 5 



5.4 File Organization 




5.4.2 Relative Files 

Relative files offer the advantage of random access, which is the ability to access 
any record in a file directly. Record lengths are fixed. Data space between the end of 
the last field and the carriage return line-feed is padded with blanks. The carriage 
return and line-feed occupy the last two bytes of the record. The number of bytes 
occupied by the fields, field delimiters, and the carriage return line-feed cannot exceed 
the specified record length. The following diagram shows a relative file composed of 
three records. 



FILE.2 



RECORD 1 


"FIELD ONE'Y'FIELD TWO","FIELD THREE"cr/lf 


RECORD 2 


"FIELD 1 "/'FIELD TWO"," " cr/lf 


RECORD 3 


111,222,3.3,444,5.5 cr/lf 








-* IvCLOlu ICligLnS IIXCU" ^^ 



Figure 5-2. Relative File 



The same rules regarding commas, quotation marks, and null strings in sequential 
files apply to relative files. The following program creates the relative file diagrammed 
above. 
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CREATE FILE, 2 RECL 40 AS 2 
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'RI 



NT 
NT 
NT 



A* = 

o ■*- _ 
jj. $ _ 

c$ = 
D$ = 
E$ = 
F$ = 
GZ = 
HZ = 
I 

j y - 
K 

*2 t i 
#2 »2 
#2 »3 



"FIELD 
"FIELD 
"FIELD 
"FIELD 
"FIELD 

1 1 1 



3.3 

aaa 

5 . 5 
A$ 
D$ 



ONE" 
TWO" 
THREE 
1 



B$ 
E$ 
HI 



C$ 
F$ 

I » 




SI 



Random access to a relative file is accomplished by specifying a relative record 
number. The relative record number is entered in all PRINT # and READ # statements 
after the file identification number. The two numbers are separated with a comma. In 
the following example, 5 is the relative record number. 



int » : 



5 VARIABLE!'*. » UARIABLE2Z 



CBASIC locates each record on a randomly accessed file by taking the relative record 
number, subtracting 1, and multiplying that difference by the record length. The result 
is a byte displacement value for the desired record measured from the beginning of the 
file. The record to be accessed must be specified in each READ # or PRINT # statement 
executed. Each READ # and PRINT # statement executed accesses the next specified 
record. The following program reads the first three fields from record three in FILE.2. 

IF END *20 THEN 200 

OPEN "FILE.2" RECL 40 AS 20 

READ #20,35 FIELD1$» FIELD2$t FIELD3 

PRINT FIELD1$» FIELD2$, FIELD3 

2 END 
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5.4 File Organization 



The data types of the variables in the READ # statement must match the data 
contained in the fields being read. Executing the above program outputs the following 
display on screen. 



1 1 1 



3,3 



5.5 Maintaining Files 

CBASIC uses the operating system file accessing routines to store and retrieve data 
in disk files. All data is represented in character format using the ASCII code. Programs 
can create, open, read, write, and close data files with the following CBASIC statements. 
Each statement is described in more detail in Section 3. 

■ CREATE originates a new data file on disk. The CREATE statement erases a 
preexisting file of the same name before creating the new file. 

■ OPEN procures an existing file for reading or updating. If the file does not 
exist, the program processes an end-of-file condition. 

■ FILE procures an existing file for reading or updating. If the file does not exist, 
the FILE statement creates it. 

■ READ # accesses a specified file and assigns the data sequentially, field by field, 
into specified variables. Data can also be accessed from a specified record. 

■ PRINT # outputs data to a specified file and assigns the data sequentially into 
fields from specified variables. Data can also be output to a specified record. 

■ PRINT USING # outputs data to a specified file using formatted printing 
options. 

■ CLOSE deactivates a file from processing. The specified file is no longer available 
for input or output until reopened. 

■ DELETE deactivates a file from processing and erases it from the disk surface. 



End of Section 5 
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Section 6 
Machine Language Interface 



CBASIC's machine level environment is somewhat advanced. To understand this 
section, you should have a working knowledge of CP/M, assembly language, and a 
familiarity with elementary computer architecture. Differences between CBASIC's 8-bit 
and 16-bit formats are most visible at the machine level. 



6.1 Memory Allocation 

The operating system loads the CBASIC run-time interpreter into the Transient 
Program Area (TPA) to execute CBASIC programs. The memory available in the TPA 
is partitioned into six areas of varying size. The following diagram shows memory 
allocation in the the CP/M TPA. For the 8-bit (8080) version, addresses are absolute. 
In the 16-bit (8086) version, addresses are offsets from either the code or data segments. 



FFFFH 



100H 
OH 



CP/M Operating System 



Free Storage Area (FSA) 



Computational Stack Area (CSA) 



Variable Storage Area (VSA) 



Intermediate Code Area (ICA) 
(compiled source program) 



Real Constant Area (RCA) 



CRUN 
(runtime interpreter) 



Area reserved for CP/M 



Figure 6-1. CP/M Memory Allocation 
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The area extending from the base of memory up to hexadecimal address 100H 

is reserved for CP/M. 

CP/M loads the run-time Interpreter at the base of the TPA starting at 100H. 

The rest of the TPA is partitioned into five areas used by the run-time Interpreter 

during program execution. 

The Real Constant Area (RCA) holds all real numbers defined as constants in 

a CBASIC program. If a constant is used more than once in a program, it 

appears only once in the RCA. Real constants require eight bytes of storage 

space. 

The Intermediate Code Area (ICA) stores the intermediate code generated by 

the Compiler. The Interpreter fetches the actual computer instructions from the 

ICA during program execution. 

The Variable Storage Area (VSA) reserves space to store the current value of 

each variable in the program. The VSA contains all variables passed through 

COMMON statements to chained programs. COMMON variables always appear 

first in the VCA. The VCA reserves eight bytes of storage space for each variable, 

regardless of the data type. For array and string variables, the actual value of 

the variable is stored in the Free Storage Area. The value stored in the VSA 

points to the actual value in the FSA. 

The Computational Stack Area (CSA) is fixed at 160 bytes of memory. The 

CSA evaluates expressions and passes parameters to CBASIC predefined and 

user-defined functions. There is room to place 20 eight-byte real numbers on 

the stack. 

The Free Storage Area (FSA) stores arrays, strings and file buffers. Variably 

sized blocks of memory are allocated from the FSA as required and returned 

when no longer needed. 

The CP/M operating system tracks occupy the very top of memory. A 16-bit 

address at 0006H and 0007H points to the beginning of CP/M. 




The starting and ending address for each partition in the TPA varies for different 
programs. Once allocated however, the amount of memory occupied by each partition 
remains fixed during program execution. 
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6.2 Internal Data Representation 



6.2 Internal Data Representation 



CBASIC machine level representation varies somewhat for real numbers, integers, 
strings, and arrays. 

■ REAL NUMBERS are stored in binary coded decimal (BCD) floating-point 
form. Each real number occupies eight bytes of memory, as shown in the fol- 
lowing diagram. The high-order bit in the first byte (byte 0) contains the sign 
of the number. The remaining seven bits in byte contain a decimal exponent. 
Bytes 1 through 7 contain the mantissa. Two (BCD) digits occupy each of the 
seven bytes in the mantissa. The number's most significant digit is stored in 
high-order four bits of byte 7. The floating decimal point is always situated to 
the left of the most significant digit. 



14 BCD DIGIT MANTISSA 



BYTES 



XX 


XX 


XX 


XX 


XX 


XX 


XX 


XX 





1 


2 


3 


4 


5 


6 


7 



BITS 



exponent 



XXXXXXXX 

12 3 4 5 6 7 



exponent s 



-number's 
sign bit 



Figure 6-2. Real Number Storage 
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INTEGERS are stored in two bytes of memory space with the low-order byte 
first, as shown in the following diagram. Integers are represented as 16-bit two's 
complement binary numbers. Integer values are limited to plus or minus 32767. 



LOW-ORDER BYTE 
STORED FIRST 



HIGH-ORDER 
BYTE 



XXX XX xxxxxxxxxxx 

BITS 8 9 10 11 12 13 14 15 1 2 3 4 5 6 7 

SIGN 
BIT 




Figure 6-3. Integer Storage 

STRINGS are stored as a sequential list of ASCII representations. The length 
of a string is stored in the first byte, followed by the actual ASCII values. The 
maximum number of characters in a string is 255 

ARRAYS, both numeric and string, are allocated space in the Free Storage Area 
as required. Eight bytes are reserved for each element of an array containing 
real numbers and two bytes for each element of an integer array. String arrays 
are allocated three bytes for each entry. A dope vector precedes each array. The 
dope vector consists of one byte to indicate the number of dimemsions, and 
two additional bytes per dimension to indicate an offset value. 



6.3 Assembly Language Interface 

CBASIC supports statements and functions that enable assembly language routines 
to be executed from CBASIC programs. 

■ CALL statement 

■ SAVEMEM statement 

■ PEEK function 

■ POKE statement 

■ SADD function 

■ VARPTR function 
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The assembler linkage process for both 8-bit and 16-bit environments consists of 
four steps. 

1. Write and debug an assembly language routine. 

2. Configure the routine for use with CBASIC. Create a .COM file for 8080 
routines, or a .CMD file for 8086 routines. 

3. Load the routine using the proper SAVEMEM parameters. 

4. Write a CBASIC program to CALL the assembly routine. 

There are differences in the architecture of 8-bit and 16-bit microprocessors. There- 
fore, procedures for linking to assembly language routines differ in the two systems. 
The following demonstration programs for both versions link to assembly routines to 
perform three simple operations. 

■ Input a character string from the keyboard. 

■ Pass the address of the string to an assembler routine. 

■ Print the string using a BDOS function call. 
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6.4 CBASIC 8-bit (8080) Demonstration Program 

Enter the following 8080 assembly language program into a file named 8080.ASM. 



ORG 



C0N$0UT 

PRINT$ 

BD0S 



0E786H 
E0U 
EQU 
EQU 




PARAM 
START 



JMP 
DW 



LHLD 

MOV 

INK 

M0U 

XCHG 

MOV 

INK 



START 




PARAM 
E »M 
H 
D »M 

A ,M 
H 



5 ADDRESS IS POKED HERE 



5 POINTER TO ADDRESS OF VARIABLE 



5m0ve address to de 
5address of variable in hl 
;get length of string 
5p0int to first character 



PRINT$L00P: 
MOV 
I NX 
MVI 
PUSH 
PUSH 
CALL 
POP 
POP 
DCR 
JNZ 



E >M 

H 

C ,C0N$0UT 

H 

PSW 

BDOS 

PSN 

H 

A 

PRINT$L00P 



JGET CHARACTER 



JSET UP FOR BDOS CALL 
5SAVE H REGISTER 
5 SAVE A REGISTER 



iRESTORE REGISTERS 
DECREMENT COUNTER 
JLOOP TILL OUT OF CHARACTERS 



CR$LF 



LXI 

MVI 

CALL 

RET 

DB 

END 



D »CR$LF 
C »PRINT$ 
BDOS 

ODH MD AH >"* 



5ADDRESS OF CR$LF SEQUENCE 
5PRINT STRING 

5RETURN TO CBASIC 
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T , nRr ^ Hress in 8 080 ASM might not be correct for your particular system, 

SAVEMEM does not reveal the load address to you. iou u „ atP ment 

and specify it in the ORG statement in the assembler routme and m the CAL ;«atemen 
n the CBASIC program. Therefore, yon mnst determme the top of the TPA ,r your 
,n tne t^v F 6 d Q7H Use the fol i owlng CBASIC program 

TZrZ^Z ^yf TPA and ca.eu.ate the load address for yonr system. 



ROUND UP TO NEARESTX 



TO HEX, 



REM PROGRAM TO DETERMINE TOP OF TPA 
INPUT "ENTER SIZE OF ASSEMBLY ROUTINE. 

128 BYTE INCREMENT, "5FILE.S,.E 
REM CALCULATE TOP OF TPA AND SUBTRACT FI LE S I .E 
L0AD.ADDR=PEEK(7)*Z5B + PEEK(B)+B553B-FILE.S.E 
PRINT: PRINT LOAD.ADDR?" = LOAD ADDRESS ... CON . EW 1 
END 

If the load address for your system differ, from the ORG address in , SO^ASM, edit 
the correct address into 8080.ASM and assemble the We to create 8080.HEX. 

rwert the assembly routine into an object code file of type.COM using the CP/M 
Convert the assembly ^° u ™ > f j and CQnverts lt to binary 

Dynamic Debugging Tool, DLM^. vu l loau* <* n , nRf ar |dress 

format The R command reads the file into memory starting at the ORG address, 
format, ine iv. cummau mM fi , i R command must contain 

However, to SAVE the memory image as a.COM hie, the K commanu i 
anTfflet value to load the file at 100H. Calculate the offset value using DDT. 



iSPECIFY 100 , THEN THE LOAD ADDRESS 



A -DDT 

DDT VERS X.X 
-HI 00 E786 
E8BG 197A 

The second number displayed by DDT (197A in this case) is the offset value. Use 
the I command to specify the filename. 

- 18080 .HEX 
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Use the R command with the offset value to read the HEX file in at 100H. 

-R197A 

NEXT PC 
1 1 E 

The HEX file is converted to binary form. Now, SAVE the routine as a.COM file. 

- "C 

f\>SAVE 1 8080, COM 

A/ 

When calling or passing parameters to the assembler routine, addresses are absolute 
memory locations. The CALL statement to start execution of 8080.COM is CALL 
0E786H. To pass a parameter, information must be inserted into the routine using the 
POKE statement. The VARPTR function is used to obtain a pointer to the address of 
the string variable. The address is converted into a high and low byte, then POKEd 
directly into the routine. The routine can access the string from CBASIC's Free Storage 
Area and print it on the console. The information in the string variable can be changed 
but the length must remain constant. The following CBASIC program calls the 8080.COM 
file. 




REM RESERVE 128 BYTES AND LOAD ROUTINE 
SAOEMEM 128, "8080 ♦COM" 

PROG,BASE=(PEEK (7)*25G+PEEK (G)-128) 

P ARAM. OF FSET= PROG. BASE+3 
INPUT "ENTER STRING TO PRINT..."! LINE$ 
WHILE (LINE$ <> "DONE") 

ADDR=OARPTR(LINE$) 

BYTE2=INT< ADDR/25G) 

BYTE1=ADDR- (5YTE2*256) 

POKE PARAM. OFFSET »BYTE1 : POKE PARAM . 0FFSET+ 1 »BYTE: 
CALL 0E78GH 

INPUT "ENTER STRING TO PRINT..."? LINE$ 
WEND 
END 
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6.5 CBASIC 16-bit (8086) Demonstration Program 

Enter the following assembly language routine into a file named 8086. A86. 

CSEG 



CON^OUT 




EOU 


o 


PRINT_ 


STRING 


EQU 


9 


BDOS 
5 




ORG 
JMP 


EQU 

100H 
START 


22a 


PARAM 




DW 





;pd 


START: 











5 POKE ADDRESS HERE 



isave registers from cbasic , 
;ds points to cbasic data area 



PUSH 
PUSH 



SI 
BP 



MOV 



SI »CS: PARAM 



;get pointer 
;to address 
;of variable 



MOV 



SI »[SI ] 



;get address 
>0f variable 



XOR 
LODSB 



AX >AX 



;get string 

5LENGTH 



MOV 



C X , A X 
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PRINT_L00P: 




PUSH 


C>( 


LODSB 




PUSH 


SI 


MOV 


DL ,AL 


MOV 


CL ,CON_OUT 


INT 


BDOS 


POP 


SI 


POP 


CX 


LOOP 


PRINT LOOP 
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5GET CHARACTER 

5SET UP FOR 
5BD0S CALL 



MOV 



DX »CS:OFFSET CR LF 



5DS MUST POINT TO PROGRAM SEGMENT ON BDOS 
5CALL ELSE, DX REFERENCES AN AREA IN CBASIC 
5DATA AREA 



PUSH 

MOV 

MOV 



MOV 
INT 



DS 

AX ,CS 
DS ,AX 



5SAVE DS FOR CBASIC 

5N0W DS POINTS TO 
5SEGMENT FOR CR LF 



CL »PRINT_STRING 
BDOS 



RESTORE REGISTERS HERE 



POP 

POP 
POP 



DS 

BP 
SI 



iDS POINTS TO CBASIC 
5DATA AREA 



iRETURN TO CBASIC WITH FAR RETURN 
5 

RETF 

CR_LF DB ODH »OAH »"$" 

END 
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Use GENCMD to convert 8086. H86 to a.CMD file. Now, the assembly routine is 
ready to be called from the following CBASIC-86 program. 



SAVEME 

REM C 

REM A 

P 

REM A 

P 

I 

1*1 

REM G 

REM C 

REM C 

REM P 

REM C 



W 



M 512 
ALCUL 
ND R0 
ROG.B 
DD OF 
ARAM. 
NPUT 
HILE 
ET P0 

ADD 
ALCUL 

5YT 
ALCUL 

BYT 
OKE B 

POK 

POK 
ALL R 

CAL 

INP 
END 



t "80 
ATE T 
UND D 
ASE=( 
FSET 
OFFSE 
"ENTE 
(LINE 
INTER 
R = UAR 
ATE H 
E2=IN 
ATE L 
E1=AD 
YTES 
E PAR 
E PAR 
OUTIN 
L 100 
UT "E 



8G.CMD" 

OP OF TPA, SUBTRACT FILE SIZE 

OWN TO IB BYTE BOUNDARY 

PEEK(7)*256+PEEK(G)-512) AND OFFFOH 

WITHIN ROUTINE 

T=(PR0G.BASE+103H) 

R STRING TO PRINT..,"; LINE$ 

$<> "DONE") 

TO STRING VARIABLE 
PTR(LINE$) 
IGH BYTE OF ADDRESS 
T(ADDR/25G) 
OW BYTE OF ADDRESS 
DR-(BYTE2*25G) 
IN LOW, HIGH ORDER 

OFFSET, BYTE1: \ 

OFFSET + 1 »BYTE2 

START AT BEGINNING 



AM 
AM 
E * 
H 
NTER 



STRING TO PRINT. 



?LINE$ 



END 




In CBASIC-86, the CALL address is an offset from the beginning of the routine code 
segment. Specify the offset in the routine. When passing parameters with the POKE 
and PEEK statements, the address used is an offset from the base of the CBASIC-86 
data segment. You must determine the address of the routine in the CP/M-86 TPA. 

To calculate the program base offset value, use the address at 06H and 07H. Subtract 
the size of the file and round down to a 16 byte paragraph boundary. Once the program 
base is determined, add the offset value for the data area that you want to access. 

When control is transferred to the assembly routine, the following rules apply: 

■ The DS, SS, BP and SI registers must be saved, then restored prior to returning 
to the CBASIC-86 program. 

■ If a routine must reference data in its data segment, the DS register must be 
initialized in the routine. 

■ Return to the CBASIC-86 program with a far return. 
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VARPTR generates a pointer to access a string in the CBASIC-86 string space. The 
information in the string can be changed but the length must remain constant. Before 
passing an address to the routine, convert the address into two bytes transferrable with 
the POKE statement. 




End of Section 6 
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Section 7 - 
Compiling and Running CBASIC 

Programs 



7.1 Compiler Directives 

Compiler directives are special commands that control the processing action of the 
compiler. All compiler directives are preceded by a percent sign, % that must be entered 
in column one. CBASIC supports six Compiler directives. 

■ %LIST 

■ %NOLIST 

■ %PAGE 

■ %EJECT 

■ % INCLUDE 

■ % CHAIN 

The Compiler ignores characters following a directive on the same line. 




7.2 Listing Control 

Four compiler directives control the listing of Compiler messages. 

■ The %LIST directive turns the Compiler listing on. %LIST can be placed any- 
where in a program, and can be used any number of times in conjunction with 
%NOLIST. This allows selected portions of a program to be listed. Both direc- 
tives can affect listings to a console, printer, or disk file. 

■ The %NOLIST directive turns the Compiler listing off. 

■ The %PAGE directive sets the page length that is output to a printer. A constant 
enclosed in parentheses must be specified following the directive. For example, 
%PAGE(45) sets the page length to 45 lines. Initially, the page length is set at 
64 lines. The constant must be a positive integer value greater than zero. Any 
number of %PAGE directives can be used in a program. 

■ The % EJECT directive positions the printer to list Compiler messages at tru 
top of the next blank page of paper. The directive sends a form feed to the 
printer. 
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The % INCLUDE directive allows a specified CBASIC program to be compiled and 
executed from within another CBASIC program. % INCLUDE directives can specify 
only one file on a line, and directives cannot reference themselves. However, % INCLUDE 
directives can be nested up to six deep. The filename specified can contain a drive 
reference as in the following example. The Compiler assumes a .BAS filetype. 




Z INCLUDE B: PROGRAM 

The example includes the file PROGRAM.BAS on drive B into the compilation and 
execution of the original program. 

Because the files incorporated with % INCLUDE directives are of filetype .BAS, they 
can be compiled separately. It is easier to debug large programs if they are composed 
of small, individually tested routines. Routines to be included by the % INCLUDE 
directive must not contain an END statement. 

The % INCLUDE directive allows you to build a library of common routines, thus 
reducing programming time. System standards, such as I/O port assignments, can be 
put in included routines. If the programs are moved from one system to another, the 
INCLUDE routine is changed, and the programs must be recompiled. 

Commonly used procedures, such as searches, validation routines, or input routines, 
are candidates for INCLUDE files. All file access commands, such as READ, PRINT, 
or OPEN, can be set up as separate INCLUDE files if certain files are accessed fre- 
quently. 

You may notice that a program segment can be compiled without errors when 
compiled separately, but when combined with other routines can cause Compiler errors. 
These errors are usually quite obvious. They often result from using the same line 
number in more than one module. 



7.4 %CHAIN Directive 

The % CHAIN directive determines the maximum size of the constant, code, data, 
and variable areas to be used for a series of chained programs. This ensures that a 
chained program does not overwrite a portion of the data area passed by a previously 
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executed program. The four areas correspond to four constants specified after the 
%CHAIN directive. The four constants are separated by commas, as in the following 
example. 

7.CHAIN 10,708,0,8 

The Compiler sets each of the four areas to the values specified in the % CHAIN 
directive. Each constant must be an unsigned positive integer. 

■ The first constant is the size of the area reserved for real constants. 

■ The second constant is the size of the code area. 

■ The third constant is the area that stores values from data statements. 

■ The fourth constant is the size of the area that stores variables. 

The constants can be expressed as hexadecimal numbers by appending an H to the 
number. Areas greater than 32,767 must be written as hexadecimal values. 

The values used in the % CHAIN directive are determined by compiling each of the 
programs to be chained and using the largest value of each area. The Compiler lists 
the size of each area at the end of a compilation. For example, if three programs are 
to be chained and the CODE SIZE for the programs are 789, 1578, and 4917 bytes, 
the second constant in the % CHAIN directive is 4917. 

The % CHAIN directive is only required in the main or first program executed. 



7.5 CBASIC Compile-time Toggles 

Enter a Compiler command line using the following syntax. 

CBAS filename [disk ref] [Stoggle {toggle}] 

The .INT file is written to the drive specified in the disk ref parameter. If you do 
not specify a disk ref, the .INT file is written to the drive containing the source file. 
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The following examples show use of CBASIC Compiler toggles. 

CBAS ACC0UNT3 $BGF 

B:CBAS A:CQMPARE $GEC 

CBAS PAYROLL $B 

CBAS BrUALIDATE $E 

Compiler toggles are a series of switches that can be set when compiling a program. 
The toggles are set by typing a $ followed by the letter designations of the desired 
toggles, starting one space or more after the program name. Toggles are only set for 
the Compiler. CBASIC supports six compile-time toggles. 

Table 7-1. Compile-time Toggles 



Toggle Function 



Toggle B Suppresses the listing of the program on the console during compi- 

lation. If an error is detected, the error message is printed even if 
toggle B is set. Toggle B does not affect listing to the printer (toggle 
F) or disk file (toggle G). Initially, toggle B is off. 

Toggle C Suppresses the generation of an INT file. Because the first compilation 

of a large program is likely to have errors, this toggle provides an 
initial syntax check without the overhead of writing the intermediate 
file. Initially, toggle C is off. 

Toggle D Suppresses translation of lower-case letters to upper-case. For exam- 

ple, if toggle D is on, AMOUNT does not refer to the same variable 
as amount. If toggle D is set, all keywords must be capitalized. Ini- 
tially, toggle D is off. 

Toggle E Useful when debugging programs. If this toggle is set, it causes the 

run-time program to accompany any error messages with the CBASIC 
line number where the error occurred. Toggle E increases the size of 
the resultant INT file and, therefore, should not be used with debugged 
programs. Toggle E must be set for the TRACE option to be in effect. 
Initially, toggle E is off. 
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Toggle 



Table 7-1. (continued) 



Function 



Toggle F Causes the compiled output listing to be printed on the list device 

and the console. This provides a hard copy of the compiled program. 
Even if toggle B is set, a complete listing is provided if toggle F is 
set. Each page of the listing has a title and numbered pages. Form- 
feeds are used to advance to the top of a page. Initially, toggle F is 
off. 

Toggle G Causes the compiled output listing to be written to a disk file. The 

file containing the compiled listing has the same name as the source 
file, and a filetype of LST. If toggles G and B are specified, only 
errors are output at the console, but a disk file of the complete 
program is produced. 




Usually the disk listing is placed on the same drive as the source file. The operator 
can select another drive by specifying the desired drive, enclosed in parentheses, fol- 
lowing toggle G as shown below: 

CBAS B:TAX $G( A: ) 

Initially, toggle G is off. 



7.6 Compiler Output 

CBASIC does not require each statement of a program to be assigned a statement 
number. The only statements that must be given a statement number are those that 
have control passed to them by the GOTO, GOSUB, ON, or IF statements. During 
compilation, CBASIC assigns a sequential number to each line independent of the 
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statement number you used. The CBASIC assigned line number is the one referred to 
in error messages (if toggle E is specified) and when using the TRACE option. The line 
number takes one of three forms, 




n: 



or, 



or, 



where n is the number assigned. Usually, the colon follows the number. The * is used 
when the statement contains a user-assigned statement number that is not referenced 
anywhere in the program. The = is printed when the statement is read in from a disk 
file with a % INCLUDE directive. 

For example: 



1 : 

r> • 

3 * 10 

a 

5 
G 



print "start 
naine$= "FRED" 
3 S U b 4 

stop 



rem print n a m e 



"/.. include p r i n t r t n 

7 = 40 rem r t n to print 

8 = print n a m e $ 
3 = r e t u r n 

10: END 



rem r t n to print 



In the preceding example, statement 3 has an * because the 10 is not referenced 
anywhere in the program. This can be useful during debugging, or to help understand 
large programs written in other Basic dialects. When all unreferenced line numbers are 
removed, it is easier to see the logic of the program. 
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When an error is detected, the Compiler prints a two-letter error code, the line 
number where the error occurred, and the position of the error relative to the beginning 
of the source line. The position assumes tab characters have been expanded. 

7.7 TRACE Option 

The TRACE option is used for run-time debugging. It prints the line number of each 
statement as it is executed. The output is directed to the console even when a LPRINTER 
statement is in effect. The line number printed is the number the Compiler assigned 
to each statement. The TRACE option syntax is as follows: 

CRUN filename [TRACE [lnl [ ,ln2}]] 

Consider the following program: 

AMOUNT = 12.13 

TIME = 45.0 

PRINT TIME * AMOUNT 

If the preceding program is compiled using the following command, 

CBAS TEST $E 

and then executed with the TRACE option, 

CRUN TEST TRACE 1 *3 

the following output is produced: 

AT LINE 0001 
AT LINE 0002 
AT LINE 0003 
545 .85 

The TRACE option functions only if the toggle E is set during compilation of the 
program. 



Hlfc 
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The first number, I nl, is specifing the line number where the trace begins. The second 
number, ln2, specifies where the trace is to stop. If no line numbers are included in 
the command, the entire program is traced; if only the first line number is present, 
tracing starts at this line number and continues for all line numbers greater than the 
first number Inl. 




7.8 Cross-Reference Lister 

Besides a Compiler and an Interpreter, a Cross-reference Lister is supplied with 
CBASIC. The XREF file produces a disk file containing an alphabetized list of all 
identifiers used in a CBASIC program. The identifier usage (function, parameter, or 
global) is provided, and a list of each line where that identifier is used. 

The listing places all functions first, parameters and local variables associated with 
a function immediately follow. The functions are listed alphabetically. The output is 
usually directed to the same disk as the source file. The file created has the same name 
as the CBASIC source file and is of type XREF. The standard output is 132 columns 
wide. 

The following command is used to invoke XREF: 

XREF filename [disk ref] [$toggles] ['title'] 

The filename must be a CBASIC source program with a filetype of BAS. The disk 
reference is optional and specifies on which disk to place the cross-reference file. If the 
disk reference is not present, the listing is placed on the same drive as the source. It is 
specified as A, B, etc. 

For example, 

,-:REF PAYROLL A: 

places the cross-reference listing for PAYROLL.BAS on drive A. At least one blank 
must separate the filename and the disk reference. 

Toggles can alter the standard output of XREF. A, B, C, D, E, F, G, and H are valid 
toggles. They can be lower- or upper-case letters. At least one blank must separate the 
$ from the portion of the command line to the left. The toggles follow the $. The 
Cross-reference Lister ignores any other characters that follow the $, and precede the 
title field or end of the command line. 
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The following is a list of the Cross-reference Lister toggles and their functions: 
Table 7-2. Cross-reference Lister Toggle Functions 



Toggle 



Function 



A Causes a listing to be output to the list device and to a disk file. 

B Suppresses output to the disk. If only the B toggle is specified, no output 

is produced. 

C Suppresses the output to the disk and permits output to the list device. 

The C toggle has the same effect as specifying both the A and B toggles. 

D Causes the output to be produced 80 columns wide instead of using 

132 columns. 

E Produces output with only the identifiers and their usage. No line num- 

bers are printed. The E toggle helps document a program. You write 
the use of each identifier on the listing provided by XREF. The file 
created by XREF is edited and made into a large remark with comments 
pertaining to each variable name. By including this file with the source 
program, more documentation is provided. 

F Allows you to change the default page length of 60 lines per page. The 

desired number of lines per page is enclosed in parentheses and must 
follow the F toggle. Embedded blanks are not allowed. Form-feed char- 
acters position the printer, and are also placed in disk files. 

G Suppresses printing of the heading lines and suppresses all form-feeds. 

This toggle is used when building a disk file to be printed by a user 
utility. 

H Suppresses translation of lower-case letters to upper-case. This allows 

using XREF with programs compiled with compiler toggle D. 



The following command: 

XREF ACCT$REC B: $EAF(40) 

creates a disk file on drive B and a listing on the list device of all the identifiers and 
their usage. No line numbers are provided. Pages are limited to 40 lines. 
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The optional title field must be the last field in the command line. All characters 
following the first apostrophe on the command line up to the second apostrophe, or 
until the end of the command line, become the title. The title is printed on the heading 
line of each page of output. The title is truncated to 30 characters if the listing is 132 
columns wide, or to 20 characters if the D toggle is specified. 

The following command demonstrates the title field: 

XREF NAMES B: $AD Version 2: 1 AUG 78' 



End of Section 7 



142 






Appendix A* - 
Compiler Error Messages 



The compiler prints the following messages when a file system error or memory 
space error occurs. In each case, control returns to the operating system. 

Table A-l. File System and Memory Space Errors 



Error Meaning 



NO SOURCE FILE: filename.* AS 



The compiler cannot locate a source file on the specified disk. This file 
was used in either the CBAS2 command or a % INCLUDE directive. 



OUT OF DISK SPACE 



The compiler has run out of disk space while attempting to write either 
the INT file or the LST file. 



OUT OF DIRECTORY SPACE 



The compiler has run out of directory entries while attempting to create 
or extend either the INT file or the LST file. 

DISK ERROR 

A disk error occurred while trying to read or write to a disk file. This 
message can vary slightly in form depending on the operating system 
used. See the CP/M documentation for the exact meaning of this mes- 
sage. 

PROGRAM CONTAINS n UNMATCHED FOR STATEMENT(S) 

There are n FOR statements for which a NEXT cannot be found. 

PROGRAM CONTAINS n UNMATCHED WHILE STATEMENT(S) 

There are n WHILE statements for which a WEND cannot be found. 
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Table A-l. (continued) 



Error 



Meaning 



PROGRAM CONTAINS 1 UNMATCHED DEF STATEMENT 

A multiple line function was not terminated with a FEND statement. 
This causes other errors in the program. 

WARNING INVALID CHARACTER IGNORED 

The previous line contained an invalid character. The compiler ignores 
the character; a question mark is printed in its place. 

INCLUDE NESTING TOO DEEP NEAR LINE n 

An INCLUDE statement near line n in the source program exceeds the 
maximum level of nesting of INCLUDE files. 




Other errors detected during compilation cause a two-letter error code to be printed 
with the line number and position of the error. The error message usually follows the 
line where the error occurred. 



Table A-2. Compilation Error Codes 



Code 



BF 

BN 
CF 
CI 

CS 



Error 



A branch into a multiple line function from outside the function was 
attempted. 

An invalid numeric constant was encountered. 

A COMMON statement must be in the first line. 

An invalid filename was detected in a % INCLUDE directive. The filename 
cannot contain a ?, *, or : (except as part of a disk reference where a 
colon can be the second character of the name). 

A COMMON statement, that was not the first statement in a program, 
was detected. Only a compiler directive such as % CHAIN, a REMARK 
statement, or blank lines can precede a COMMON statement. 



144 





CBASIC Language Reference Manual 



w 

f 

$■•■ 



A Compiler Error Messages 



~TTTlTfflM 



Code 



Table A-2. (continued) 



Error 



CV An improper definition of a subscripted variable in a COMMON state- 

ment was detected. The subscript count is possibly not a constant, or 
there is more than one constant. Only one constant can appear in paren- 
theses. It specifies the number of subscripts in the defined array. 

DL The same line number was used on two different lines. Other compiler 

errors can cause a DL error message to be printed even if duplicate line 
numbers do not exist. Defining functions before use and, sometimes, if 
the DIM statement does not precede all references to an array, results in 
a DL error. 

DP A variable dimensioned by a DIM statement was previously defined. It 

either appears in another DIM statement or was used as a simple variable. 

FA A function name appears on the left side of an assignment statement but 

is not within that function. In other words, the only function name that 
can appear to the left of an equal sign is the name of the function currently 
compiled. 

FD The same function name is used in a second DEF statement. 

FE A mixed mode expression exists in a FOR statement that the compiler 

cannot correct. Probably the expression following the TO is of a different 
type than the index. 

FI An expression is a subscripted numeric variable being used as a FOR 

loop index. 

FN A function reference contains an incorrect number of parameters. 

FP A function reference parameter type does not match the parameter type 

used in the function's DEF statement. 

FU A function was referenced before it was defined, or the function was 

never defined. 

IE An expression immediately following an IF statement evaluates to type 

string. Only type numeric is permitted. 



145 



A Compiler Error Messages 



CBASIC Language Reference Manual 



Code 



IF 

IP 
IS 
IT 

IU 

MC 

MF 

MM 

MS 
ND 

NI 

NU 
OF 



Table A-2. (continued) 



Error 



A variable used in a FILE statement is of type numeric where type string 
is required. 

An input prompt string was not surrounded by quotes. 

A subscripted variable was referenced before dimensioned. 

An invalid compiler directive was encountered. A parameter required by 
the directive can be out of range or missing, or the directive was mis- 
spelled. 

A variable defined as an array in a DEF statement is used without sub- 
scripts. 

The same variable is defined more than once in a COMMON statement. 
Each variable can appear in only one COMMON statement. 

An expression evaluates to type string when an expression of type numeric 
is required. 

An invalid mixed mode was detected. Probably variables of type string 
and type numeric were combined in the same expression. 

A numeric expression was used where a string expression was required. 

A FEND statement was encountered without a corresponding DEF state- 
ment. This error could be the result of an improper DEF statement. 

A variable referenced by a NEXT statement does not match the variable 
referenced by the associated FOR statement. 

A NEXT statement occurs without an associated FOR statement. 

A branch out of a multiple line function from inside the function was 
attempted. 
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Table A-2. (continued) 



Error 



OO More than 40 ON statements were used in the program. CBASIC has an 

arbitrary limit of 40 ON statements in a single program. Notify Digital 
Research if this limit causes problems. 

PM A DEF statement appeared within a multiple line function. Functions 

cannot be nested. 

RF A multiple line function cannot call itself. 

SD A second SAVEMEM statement was encountered. A program can have 

only one SAVEMEM statement. 

SE The source line contained a syntax error. This means that a statement is 

not properly formed or a keyword is misspelled. 

SF A SAVEMEM statement uses an expression of type numeric to specify 

the file to be loaded. The expression must be a string. Possibly, the 
quotation marks were left off a string constant. 

SN A subscripted variable contains an incorrect number of subscripts, or a 

variable in a DIM statement was previously used with a different number 
of dimensions. 

SO The statement is too complex to compile; simplify it. Consider making 

the expression into two or more expressions. Please send Digital Research 
a copy of the source statement. 

TO Symbol table overflow has occurred. This means that the program is too 

large for the system being used. The program must be simplified or the 
amount of available memory increased. Smaller variable names reduce 
the amount of symbol table space used. Please inform Digital Research 
if programs generate this error. 

UL A line number that does not exist was referenced. 

US A string was terminated by a carriage return rather than by quotes. 
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VO 



WE 

WN 



Table A-2. (continued) 



Error 



Variable names are too long for one statement. This should not usually 
occur. If it does, please send a copy of the source statement to Digital 
Research. Reducing the length of variable names and reducing the com- 
plexity of the expression within the statement can eliminate the error. 

The expression immediately following a WHILE statement is not numeric. 

WHILE statements are nested to a depth greater than 12. CBASIC has 
an arbitrary limit of 12 for nesting WHILE statements. 



WU A WEND statement occurred without an associated WHILE statement. 
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Appendix B;_ 
Run-time Error Messages 



The following warning messages might be printed during execution of a CBASIC 
program. 

Table B-l. CBASIC Warning Messages 



Error 



Meaning 



NO INTERMEDIATE ¥\LE:filename 



A filename was not specified with the CRUN2 command, or no file 
of type INT with the specified filename was found on the specified 
disk. 



IMPROPER INPUT - REENTER 



This message occurs when the fields entered from the console do not 
match the fields specified in the INPUT statement. This occurs when 
field types do not match or the number of fields entered differs from 
the number of fields specified. Following this message, all values required 
by the INPUT statement must be reentered. 



Run-time errors cause a two-letter code to be printed. If the code is preceded by the 
word WARNING, execution continues. If the code is preceded by the word ERROR, 
execution terminates. If an error occurs with a code consisting of an * followed by a 
letter such as *R, the CBASIC run-time package has failed. Please notify Digital Research 
of the circumstances under which the error occurred. 
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The following table contains valid CBASIC warning codes. 
Table B-2. CBASIC Warning Codes 



Code 



Error 



DZ A number was divided by zero. The result is set to the largest valid 

CBASIC number. 

FL A field length greater than 255 bytes was encountered during a READ 

LINE statement/The first 255 characters of the record are retained; the 
other characters are ignored. 

LN The argument given in the LOG function was zero or negative. The value 

of the argument is returned. 

NE A negative number was specified before the raise to a power operator. 

The absolute value of the parameter is used in the calculation. When 
using real variables, a positive number can be raised to a negative power, 
but a negative number cannot be raised to a power. 

OF A calculation using real variables produced an overflow. The result is set 

to the largest valid CBASIC real number. Overflow is not detected with 
integer arithmetic. 

SQ A negative number was specified in the SQR function. The absolute value 

is used. 




The following table contains valid CBASIC error codes. 
Table B-3. CBASIC Error Codes 



Code 



AC 
AE 

BN 
150 



Error 



The argument in an ASC function is a null string. 

An attempt was made to access an array element before the array DIM 
statement was executed. 

The value following the BUFF option in an OPEN or CREATE statement 
is less than one or greater than 52. 
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>de 



Error 



CD 



CP 



CS 



EF 



— " "TC^haTthe main program's code 

of the code area. ^ 

p fl U lareer than the main program s data 

*j&r^%££&"*> **" to adiust "* 

of the data area. 

t he found in the directory. This occurs if the 
The file being closed cannot be found in 
RENAME function has changed the file. 

a k lareer than the main program's 
A chained program's constant area is larger t ^ ad 

constant area. Use a %CHA1N directive in the main p 
the size of the constant area. 

is larger than the main pro- 
A chained program's variable storage a ^ ^ ^ mam pro . 

A«^ P ^^^£^^ rf,ne,,,0,7 ■ w,,h, 

SAVEMEM statement, than the main prog 

., Q a fi i e ld entification number that is not active. 
A CLOSE statement specifies a hie identm 

„t ,«es a file identification number that 
An OPEN or CREATE statement uses a 

is already used. 

•f « file identification number that is not 
A DELETE statement specifies a file identm 

active. 

, 9t there is no disk or directory space 
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:«ect for the file identification nnmber. 
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Code 



Table B-3. (continued) 



Error 



ER An attempt was made to write a record of length greater than the max- 

imum record size specified in the OPEN, CREATE, or FILE statement 
for this file. 

FR An attempt was made to rename a file to an existing filename. 

FU An attempt was made to access a file that was not open. 

IF A filename was invalid. Most likely, an invalid character was found in 

the filename. A colon can never appear embedded in the name proper. ? 
and * can only appear in ambiguous filenames. This error also results if 
the filename was a null string. 

IR A record number of zero was specified in a READ or PRINT statement. 

IV An attempt was made to execute an INT file created by a version one 

compiler. To use CRUN2, a program must be recompiled using the ver- 
sion two compiler, CBAS2. This error also results from attempting to 
execute an empty INT file. 

IX A FEND statement was encountered before executing a RETURN state- 

ment. All multiple line functions must exit with a RETURN statement. 

ME The operating system reports an error during an attempt to create or 

extend a file. Usually this means the disk directory is full. 

MP The third parameter in a MATCH function was zero or negative. 

NC The source program contains a real constant outside the range of CBASIC 

real numbers. 

NF A file identification number is less than one or greater than 20, or a FILE 

statement was executed when 20 files were already active. 

NM There was insufficient memory to load the program. 

NN An attempt toj>rint a numeric expression with a PRINT USING statement 

fails because there is not a numeric field in the USING string. 
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Table B-3. (continued) 




Code 



NS 



OD 



OE 



OI 



OM 



QE 

RB 

RE 
RF 

RG 



Error 



An attempt to print a string expression with a PRINT USING statement 
fails because there is not a string field in the USING string. 

A READ statement was executed, but there are no DATA statements in 
the program, or all data items in all DATA statements were already read. 

An attempt was made to OPEN a file that does not exist and for which 
no IF END statement was in effect. 

The expression specified in an ON . . . GOSUB or an ON . . . GOTO 
statement evaluated to a number less than one or greater than the number 
of line numbers contained in the statement. 

The program ran out of dynamically allocated memory during execution. 
Space can be conserved by closing files when no longer needed, and by 
setting strings to a null string when no longer required. Also, by not using 
DATA statements, but reading the constant information from a file, space 
is saved. Large arrays can be dimensioned with smaller subscripts when 
the array is no longer required. 

An attempt was made to print a string containing a quotation mark to 
a file. Quotation marks can only be written to files when using the PRINT 
USING option of the PRINT statement. 

Random access was attempted to a file activated with the BUFF option 
specifying more than one buffer. 

An attempt was made to read past the end of a record in a fixed file. 

A recursive function call was attempted; CBASIC does not support recur- 
sion. 

A RETURN statement occurred for which there was no GOSUB state- 
ment. 



RU A random read or print was attempted to a stream file. 
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Code 



Table B-3. (continued) 



Error 



SB An array subscript was used which exceeds the boundaries for which the 

array was defined. 

SL A concatenation operation resulted in a string greater than the maximum 

allowed string length. 

SO The file specified in a SAVEMEM statement cannot be located on the 

referenced disk. The expression specifying the filename must include the 
filetype if one is present. A filetype of COM is not forced. 

SS The second parameter of a MID$ function was zero or negative, or the 

last parameter of a LEFTS, RIGHTS, or MID$ function was negative. 

TL A TAB statement contains a parameter less than one. 

UN A PRINT USING statement was executed with a null edit string, or an 

escape character is the last character in an edit string. 

WR An attempt was made to write to a stream file after it was read, but 

before it was read to the end of the file. 




End of Appendix B 
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Appendix C 
CBASIC Key Words 



ABS 


ELSE 


LE 


PRINT 


STRS 


AND 


END 


LEFTS 


RANDOMIZE 


SUB 


AS 


EQ 


LEN 


READ 


TAB 


ASC 


EXP 


LET 


RECL 


TAN 


ATN 


FEND 


LINE 


RECS 


THEN 


BUFF 


FILE 


LOG 


REM 


TO 


CALL 


FLOAT 


LPR1NTER 


REMARK 


UCASES 


CHAIN 


FN* 


LT 


RENAME 


USING 


CHR$ 


FOR 


MATCH 


RESTORE 


VAL 


CLOSE 


FRE 


MID$ 


RETURN 


VARPTR 


COMMANDS 


GE 


NE 


RIGHTS 


WEND 


COMMON 


GO 


NEXT 


RND 


WHILE 


CONCHAR% 


GOSUB 


NOT 


SADD 


WIDTH 


CONSOLE 


GOTO 


ON 


SAVEMEM 


XOR 


CONSTAT% 


GT 


OPEN 


SGN 


% CHAIN 


COS 


IF 


OR 


SIN 


%EJECT 


CREATE 


INITIALIZE 


OUT 


SIZE 


%INCLUDE 
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DATA 


INP 


PEEK 


SQR 


%LIST 


DEF 


INPUT 


POKE 


STEP 


%NOLIST 


DELETE 


INT 


POS 


STOP 


%PAGE 


DIM 


INT% 










"For FN, see user-defined functions. 



End of Appendix C 
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Table D-l. 


Conversion Table 








DECIMAL 


ASCII 


HEX 


DECIMAL ASCII 


HEX 


DECIMAL 


ASCII 


HEX 





NUL 


00 


44 


5 


2C 


88 


X 


58 


1 


SOH 


01 


45 


- 


2D 


89 


Y 


59 


2 


STX 


02 


46 




2E 


90 


Z 


5A 


3 


ETX 


03 


47 


/ 


2F 


91 


[ 


5B 


4 


EOT 


04 


48 





30 


92 


\ 


5C 


5 


ENQ 


05 


49 


1 


31 


93 


] 


5D 


6 


ACK 


06 


50 


2 


32 


94 


* 


5E 


7 


BEL 


07 


51 


3 


33 


95 




5F 


8 


BS 


08 


52 


4 


34 


96 


v 


60 


9 


HT 


09 


53 


5 


35 


97 


a 


61 


10 


LF 


0A 


54 


6 


36 


98 


b 


62 


11 


VT 


OB 


55 


7 


37 


99 


c 


63 


12 


FF 


OC 


56 


8 


38 


100 


d 


64 


13 


CR 


0D 


57 


9 


39 


101 


e 


65 


14 


SO 


0E 


58 




3A 


102 


f 


66 


15 


SI 


OF 


59 


5 


3B 


103 


g 


61 


16 


DLE 


10 


60 


< 


3C 


104 


h 


68 


17 


DC1 


11 


61 


= 


3D 


105 


i 


69 


18 


DC2 


12 


62 


> 


3E 


106 


i 


6A 


19 


DC3 


13 


63 


? 


3F 


107 


k 


6B 


20 


DC4 


14 


64 


<& 


40 


108 


1 


6C 


21 


NAK 


15 


65 


A 


41 


109 


m 


6D 


22 


SYN 


16 


66 


B 


42 


110 


n 


6E 


23 


ETB 


17 


67 


C 


43 


111 


o 


6F 


24 


CAN 


18 


68 


D 


44 


112 


P 


70 


25 


CR 


19 


69 


E 


45 


113 


q 


71 


26 


SUB 


1A 


70 


F 


46 


114 


r 


72 


27 


ESC 


IB 


71 


G 


47 


115 


s 


73 


28 


FS 


1C 


72 


H 


48 


116 


t 


74 


29 


GS 


ID 


73 


1 


49 


117 


u 


75 


30 


RS 


IE 


74 


J 


4A 


118 


V 


76 


31 


US 


IF 


75 


K 


4B 


119 


w 


77 
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Table D-l. (continued) 



DECIMAL 


ASCII 


HEX 


DECIMAL 


ASCII 


HEX 


DECIMAL 


ASCII 


HEX 


32 


SP 


20 


76 


L 


4C 


120 


X 


78 


33 


t 


21 


77 


M 


4D 


121 


y 


79 


34 


a 


22 


78 


N 


4E 


122 


z 


7A 


35 


# 


23 


79 


O 


4F 


123 


{ 


7B 


36 


$ 


24 


80 


P 


50 


124 


1 


7C 


31 


% 


25 


81 


Q 


51 


125 


} 


7D 


38 


& 


26 


82 


R 


52 


126 




7E 


39 


i 


27 


83 


S 


53 


127 


DEL 


7F 


40 


( 


28 


84 


T 


54 








41 


) 


29 


85 


U 


55 








42 


* 


2A 


86 


V 


56 








43 


+ 


2B 


87 


w 


57 











End of Appendix D 
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Appendix t 
Glossary 




address: Location in memory. 

ambiguous file specification: File specification that contains either of the Digital Research 
wildcard characters, ? or *, in the filename or filetype or both. When you replace 
characters in a file specification with these wildcard characters, you create an ambiguous 
filespec and can reference more than one file in a single command line. 

applications program: Program that needs an operating system to provide an envi- 
ronment in which to execute. Typical applications programs are business accounting 
packages, word processing, and mailing list programs. 

argument: Variable or expression value that is passed to a procedure or function and 
substituted for the dummy argument in the function. Same as "actual argument" or 
"calling argument". Used interchangeably with "parameter". 

array: Data type that is itself a collection of individual data items of the same data 
type. Term used to describe a form of storing and accessing data in memory, visualized 
as matrices. The number of extents of an array is the number of dimensions of the 
array. A one dimensional array is essentially a list. 

ASCII: Acronym for American Standard Code for Information Interchange. ASCII is 
a standard code for representation of the numbers, letters, and symbols that appear 
on most keyboards. 

assembler: Language translator that translates assembly language statements into 
machine code. 

assignment statement: Statement that assigns the value of an expression on the right 
side of an equal sign to the variable name on the left side of the equal sign. 

back-up: Copy of a file or disk made for safe keeping, or the creation of the file or 
disk. 

binary: Base two numbering system containing the two symbols zero and one. 
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bit: Common contraction for "binary digit". "Switch" in memory that can be set to 
on (1) or off (0). Eight bits grouped together comprise a byte. 

buffer: Area of memory that temporarily stores data during the transfer of infor- 
mation. 

byte: Unit of memory or disk storage containing eight bits. 

call: Transfer of control to a computer program subroutine. 

chain: Transfer of control from the currently executing program to another named 
program without returning to the system prompt or invoking the run-time monitor. 

code: Sequence of statements of a given language that make up a program. 

command: Instruction or request for the operating system or a system program to 
perform a particular action. Generally, a Digital Research command line consists of a 
command keyword, a command tail usually specifying a file to be processed, and a 
carriage return. 

common: Variables used by a main program and all programs executed through a 
chain statement. 

compiler: Language translator that translates the text of a high level language into 
machine code. 

compiler directive: Reserved words that modify the action of the compiler. 

compiler error: Error detected by the compiler during compilation; usually caused 
by improper formation of language statement. 

compiler toggle: "Switch" to modify the output of the compiler. 

concatenate: Join one string to another or one file to another. 

concatenation operator: Symbol peculiar to a given language that instructs the com- 
piler to combine two unique data items into one. 

console: Primary input/output device. The console consists of a listing device such as 
a screen and a keyboard through which the user communicates with the operating 
system or the applications program. 



160 






CBASIC Language Reference Manual 



E Glossary 




constant: String or numeric value that does not change "throughout program execu- 
tion. 

control character: Nonprinting character combination that sends a simple command 
to the operating system or applications program. To enter a Control character, press 
the Control (CTRL) key on your terminal and strike the character key specified. 

control statement: Language statement that transfers control or directs the order of 
execution of instructions by the processor. 

cursor: One-character symbol that can appear anywhere on the video screen. The 
cursor indicates the position where the next keystroke at the console will have an effect. 

data: Information; numbers, figures, names, and so forth. 

data base: Large collection of information, usually covering various aspects of related 
subject matter. 

data file: Nonexecutable file of similar information that generally requires a command 
file to process it. 

data structure: Mechanism, including both storage layout and access rules, by which 
information can be stored and retrieved within a computer system. Data structures can 
reside in memory or on secondary storage. System tables such as symbol tables, matrices 
of numerical data, and data files are examples of data structures. 

data type: Class or use of the data; for example, integer, real or string. 

debug: Remove errors from a program. 

default: Values, parameters or options a given command assumes if not otherwise 
specified. 

delimiter: Special characters or punctuation that separate different items in a com- 
mand line or language statement. 

dimension: Refers to the number of extents of an array. A one dimensional array is 
essentially a list of the elements of the array. A two dimensional array can be visualized 
as a matrix of rows and columns of storage space for the elements of the array. A 
three dimensional array can be thought of as a geometric solid having volume, and so 
forth. 
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directory: Portion of a disk that contains entries for each file on the disk. In response 
to the DIR command, CP/M and MP/M systems display the file specifications stored 
in the directory. 

disk, diskette: Magnetic media used to store information. Programs and data are 
recorded on the disk in the same way that music is recorded on a cassette tape. The 
term "diskette" refers to smaller capacity removable floppy diskettes. The term "disk" 
can refer to a diskette, a removable cartridge disk, or a fixed hard disk. 

disk drive: Peripheral device that reads and writes on hard or floppy disks. CP/M 
and MP/M systems assign a letter to each drive under their control. 

drive specification: Alpha character A-P followed by a colon that indicates the CP/ 
M or MP/M drive reference for the default or specified drive. 

dummy argument: Argument used in the definition of a command or language state- 
ment (especially a function) that holds a place that will later contain a usable "actual" 
or "calling" argument that is passed to the function by a calling statement. Same as 
"formal argument". 

editor: Utility program that creates and modifies text files. An editor can be used to 
create documents or code for computer programs. 

element: Individual data item in an array. 

executable: Ready to run on the processor. Executable code is a series of instructions 
that can be carried out on the processor. For example, the computer cannot "execute" 
names and addresses, but it can execute a program that prints names and addresses 
on mailing labels. 

execute a program: Start a program running. When the program is executing, a 
process is executing a sequence of instructions. 

FCB: File Control Block. Structure used for accessing files on disk. Contains the drive, 
filename, filetype and other information describing a file to be accessed or created on 
the disk. 

field: Portion of a record; length and type are defined by the programmer. One or 
more fields comprise a record. 
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fil , Collection of related records coning characters, mstructiot* or data; usually 
^.d on aTsk under a unique file specification. 

n The filename can include 1-8 alpha, numeric 

sr^^^'^ 2 ^ should te " somethins about the 

numeric and/or some specal charaa r ^ f ^ f , es to be proce ssed have specfic 
name by a penod. Certam programs requ.re 

filetypes. . 

c\ .„ „,ri™c the information stored in 
fi,e access: Refers to methods of entering a file to retneve 

the file. , 

file specification: Unique fi,e .dentifie, M»*^*£ gSS^I^ 
an optional drive specification followed by a ^J^ \ ome Dl tal Researc 
acters, and an optional period »J^1 and password of 1-8 characters fol- 
operating systems »«™ J" 1 "^ ™c <» P^ ^^ ^ ^ speaal 
S^^XeTiS. ^ch file specficafion, 

a u.n Ait* is to be accessed randomly— not in 
5L25&KSS ^nonvlrying lengths of the records composing 

the file. . , 

notation; a real number. 

• MA „sed to store information. Floppy disks are man- 
floppy disk: Flexible magnetic disk used to 
ufactured in 5'A and 8 inch diameters. 

flowchart- Graphic diagram tnat uses special symbols to indicate the input, output 

an7flow of control of part or all of a program. 

flow of control: Order of the execution of statements within a program. 

^^^^^^^^^ 
flatted prinfing: Output specially designed m a certain pattern and achieved 
rCgh particular coded language statements. 
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fragmentation: Division of storage area in a way that causes areas to be wasted. 

function: Subroutine to which you can pass values and which returns a value. Useful 
when the same code is required repeatedly, as the program can call the function at any 
time. 

global: Relevant throughout an entire program. 

hex file: ASCII-printable representation of a code or data file in hexadecimal notation. 

hexadecimal notation: Notation for the base 16 number system using the symbols 0, 
1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, and F to represent the sixteen digits. Machine 
code is often converted to hexadecimal notation because it can be more easily under- 
stood. 

high bound: Upper limit of one dimension of an array. 

high-level language: Set of special words and punctuation that allows a programmer 
to code software without being concerned with internal memory management. 

identifier: String of characters used to name elements of a program, such as variable 
names, reserved words, and user-defined function names. Commonly used synony- 
mously with "variable name". 

include: Call an external file into the code sequence of a program at the point where 
the include statement is executed. 

initialize: Set a disk system or one or more variables to initial values. 

I/O: Abbreviation for input/output. 

input: Data entered to an executing program, usually from an operator typing at the 
terminal or by the program reading data from a disk. 

instruction: Set of characters that defines an operation. 

integer: Positive or negative nonexponential whole number that does not contain a 
decimal point. 

interface: Object that-allows two independent systems to communicate with each 
other, as an interface between the hardware and software in a microcomputer. 
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intermediate code: Code generated by the syntactical and semantic analyzer portions 
of a compiler. 

interpreter: Computer program that translates and executes each source language 
statement before translating and executing the next one. 

ISAM: Abbreviation for Indexed Sequential Access Method. 

key: Particular field of a record on which the processing is performed. 

keyword: Reserved word with special meaning for statements or commands. 

kilobyte: 1024 bytes denoted as IK. 32 kilobytes equal 32K. 1024 kilobtyes equal 
one megabyte, or over one million bytes. 

linker: System software module that connects previously assembled or compiled pro- 
grams or program modules into a unit that can be loaded into memory and executed. 

linked list: Data structure in which each element contains a pointer to its predecessor 
or successor (singly linked list) or both (double linked list). 

list device: Device such as a printer onto which data can be listed or printed. 

listing: Output file created by the compiler that lists the statements in the source 
program, the line numbers it has assigned to them, and possibly other optional infor- 
mation. 

literal data: Verbatim translation of characters in the code, such as in screen prompts, 
report titles and column headings. 

load: To move code from storage into memory for execution. 

local variable: Relevant only within a specific portion of a program, such as within 
a function. 

logged-in: Made known to the operating system, in reference to drives. A drive is 
logged-in when it is selected by the user or an executing process. 




165 



E Glossary 



CBASIC Language Reference Manual 



logical: Representation of something such as a console, memory or disk drive that 
might or might not be the same in its actual physical form. For example, a hard disk 
can occupy one physical drive, and yet you can divide the available storage on it to 
appear to the user as if there were several different drives. These apparent drives are 
the logical drives. 

logical device: Reference to an I/O device by the name or number assigned to the 
physical device. 

logical operator: NOT, AND, OR, and XOR. 

lower bound: Lower limit of one dimension of an array. 

machine code: Output of an assembler or compiler to be executed directly on the 
target processor. 

machine language: Instructions directly executable by the processor. 

memory: Storage area within and/or attached to a computer system. 

microprocessor: Silicon chip that is the Central Processing Unit (CPU) of the micro- 
computer system. 

mixed mode: Combination of integer and real or numeric and string values in an 
expression. Mixed string and numeric operations are generally not allowed in high 
level languages. 

mnemonic operator: Alphabetical symbol for algebraic operator: LT, LE, GT, GE, 

NE, and EQ. 

module: Section of software having well-defined input and output that can be tested 
independently of other software. 

multiple-line function: Function composed of a function definition statement and one 
or more additional statements. 

numeric constant: Real or integer quantity that does not vary within the program. 

numeric variable: Real or integer identifier to which varying numeric quantities can 
be assigned during program execution. 
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null string: A string that contains no character; essentiallyan empty string. 

object code: Output of an assembler or compiler that executes on the target processor. 

open: System service that informs the operating system of the manner in which a 
given resource, usually a disk file, is intended to be used. 

operating system: Collection of programs that supervises the execution of other pro- 
grams and the management of computer resources. An operating system provides an 
orderly input/output environment between the computer and its peripheral devices, 
enabling user programs to execute safely. 

operation: Execution of a piece of code. 

option: One of a set of parameters that can be part of a command or language 
statement. Options are used to modify the output of an executing process. 

output: Data that the processor sends to the console, printer, disk, or other storage 
media. 

parameter: Value supplied to a command or language statement that provides addi- 
tional information for the command or statement. Used interchangeably with "argu- 
ment." An actual parameter is a value that is substituted for a dummy or formal 
argument in a given procedure or function when it is invoked. 

peripheral device: Devices external to the CPU. For example, terminals, printers, and 
disk drives are common peripheral devices that are not part of the processor, but are 
used in conjunction with it. 

pointer: Data item whose value is the address of a location in memory. 

primitive: Most basic or fundamental unit of data such as a single digit or letter. 

process: Program that is actually executing, as opposed to being in a static state of 
storage on disk. 

program: Series of specially coded instructions that performs specific tasks when 
executed on a computer. 

prompt: Any characters displayed on the input terminal to help the user decide what 
the next appropriate action is. A system prompt is a special prompt displayed by the 
operating system, indicating to the user that it is ready to accept input. 
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random access: Method of entering a file at any record number, not necessarily the 
first record in the file. 

random access file: File structure in which data can be accessed in a random manner, 
irrespective of its position in the file. 

random number: Number selected at random from a set of numbers. 

real number: Numeric value specified with a decimal point; same as "floating point 
notation." 

record: One or more fields usually containing associated information in numerical 
or textual form. A file is composed of one or more records and generally stored on 
disk. 

record number: Position of a specific record in a fixed-length file, relative to record 
number 1. A key by which a specific record in a fixed file is accessed randomly. 

recursive: Code that calls itself. 

relational operator: Comparison operator. The following set of operators expressed 
in algebraic or mnemonic symbols: LT, LE, NE, EQ, GT, GE, EQ. A relational operator 
states a relationship between two expressions. 

reserved word: Keyword that has a special meaning to a given language or operating 
system. 

return value: Value returned by a function. 

row-major order: Order of assignment of values to array elements in which the first 
item of the subscript list indicates the number of "rows" in the array. 

run a program: Start a program executing. When a program is running, the micro- 
processor chip is executing a series of instructions. 

run-time error: Error occurring during program execution. 

run-time monitor: Program that directly executes the coded instructions generated 
by a compiler/interpreter. 
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sequential access: Type of file structure in which data dm only be accessed serially, 
one record at a time. Data can be added only to the end of the file and cannot be 
deleted. An example of a sequential access media is magnetic tape. 

source program: Text file that is an input file for a processing program, such as an 
editor, text formatter, assembler or compiler. 

statement: Defined way of coding an instruction or data definition using specific 
keywords in a specific format. 

storage: Place for keeping data temporarily in memory or permanently on disk. 

stream organization: Type of file organization used when data is to be accessed 
sequentially. Can contain variable length records. 

string constant: Literal data, as in a screen prompt, column heading, or title of a 
report. 

string variable: Identifier of type string to which varying strings can be assigned during 
program execution. 

subroutine: Section of code that performs a specific task, is logically separate from 
the rest of the program, and can be prewritten. A subroutine is invoked by another 
statement and returns to the place of invocation after executing. Subroutines are useful 
when the same sequence of code is used more than once in a program. 

subscript: Integer expression that specifies the position of an element in an array. 

subscript list: Numeric value appended to a variable name that indicates the number 
of elements in each dimension in the array of that name. Each dimension must have 
a value in the subscript list indicating the number of elements for which to allocate 
storage space. 

syntax: Rules for structuring statements for an operating system or programming 
language. 

toggle: "Switch" enabled by a special code in the command line that modifies the 
output of the executing program. 

trace: Option used for run-time debugging. The trace option generally lists each line 
of code as it executes to enable the programmer to note where a problem occurs. 
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upward-compatible: Term meaning that a program created for the previously released 
operating system or compiler runs under a later release of the same software program. 

user-defined function: Set of statements created and given a function name by the 
user. The function performs a specific task and is called into action by referencing the 
function by name. 

utility: Tool. Program or module that facilitates certain operations, such as copying, 
erasing and editing files, or controlling the cursor positioning on the video screen from 
within a program. Utilities are created for the convenience of programmers and appli- 
cations operators. 

value: Quantity expressed by an integer or real number. 

variable: Name to which the program can assign a numerical value or string. 

variable length: Usually refers to records, where each record in a file is not necessarily 
the same length as another. 

variable name: Same as variable. 

wildcard characters: Special characters, ? and *, that can be included in a Digital 
Research filename and/or filetype to identify more than one file in a single file speci- 
fication. 




End of Appendix E 



v. ■ ■ • .-■: 

■'. .-'..■■'■■ •■ ; 

■f ■» ; "_..' ..*«• v«. ,"^B 



170 




Index 




ABS function, 14 
algebraic operators, 9 
AND Operator, 11 
array, 5, 8, 22, 124 

physical storage area of, 

referenced, 8 

variables, 8 
AS expression, 28, 64 
ASC function, 15 
assembler linkage process 

16-bit, 125 

8-bit, 125 
assembly language, 68, 85 

interface, 124 
assigned line number, 137 
assignment statements, 55 
asterisk fill, 112 
ATN function, 16 



B 



backslash, 2, 6 

balanced parentheses, 9 

BAS files, 1, 134 

s 
base offset value, 131 

binary constant, 7 

bounds checking, 9 

BUFF Expression, 65 

byte displacement value, 118 



CALL address 8086, 128 
CALL statement, 17, 86 



calling parameters, 128 

capitalization, 13 

CBASIC-86, 131, 132 

CBASIC key words, 155-156 

CHAIN statement, 18, 21 

CHR$ function, 19 

CLOSE statement, 20, 45, 119 

CMD file, 131 

colon, 2 

COMMANDS function, 21 

commas, embedded, 112 

comments, 2 

COMMON statement, 22, 105 

Compiler, 1 

directives, 133 

error codes, 144-148 

error messages, 136 

file system errors, 143-144 

listing, 133 

toggles, 135-136 

starting the, 3 
Computational Stack Area, 121, 122 
concatenation operator, 11 
CONCHAR% function, 24, 107 
console device width, 25 
console input and output, 107 
console output, 108 
CONSOLE statement, 25, 70 
constants, 5, 9 

CONSTAT% function, 26, 107 
continuation character, 2, 5, 29, 79 
control characters, 6 
COS function, 27 
CP/M, 49, 57, 64, 80, 86 
CREATE statement, 28, 119 
Cross-reference Lister, 1, 140 
CTRL-C, 49 
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CTRL-U, 49 
CTRL-Z, 49 
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data area overwriting, 134 
data fields, 108 
data files, 

relative, 117 

sequential, 115 
DATA statement, 29, 81, 107 
data types, 5 
DDT, 127 

Decimal-ASCII-Hex Table, 157 
DEF statement, 30, 104, 105 
DELETE statement, 31, 45, 119 
delimiters, 115 
DIM statement, 23, 32, 105 
dimension, 9 
dope vector, 124 
dummy argument, 104 



ELSE statement, 43, 44 
END statement, 33, 134 
EQ operator, 10 
escape characters, 114 
EXP function, 34 
exponential notation, 7 
expression list, 109 
expressions, 9 



FEND statement, 35, 105 
fields, 114 __ 

file organization, 114 
FILE statement, 36, 119 
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files, 114 

fixed format, 7 

fixed-length string field, 108 

FLOAT function, 37 

floating-point number, 7, 16 

FN, 5 

FOR loop, 39 

FOR statement, 38, 61 

format string, 73, 106 

FRE function, 40 

Free Storage Area, 121 

functions, 5, 103 

definition, 104 

names, 103 

references, 106 



GE operator, 10 

GENCMD, 131 

GO statement, 41, 42 

GOSUB statement, 41, 62, 79, 137 

GOTO statement, 42, 61, 105, 137 

GT operator, 10 



H 

hexadecimal constants, 7, 135 
high-level language features, 1 



I 



identifier, 5-8, 61, 140 

usage, 140 
IF END statement, 20, 28, 31, 45 
IF statement, 43-44 
individual record lengths, 115 
initialize, 8 
INITIALIZE statement, 47 






INT file, 1 

INP function, 48, 107 

INPUT statement, 49-50, 74-76, 107 

INPUT LINE statement, 76, 107 

INT function, 51 

INT %Function, 52 

integers, 5-7, 123 

Intermediate Code Area, 122 

intermediate files, 1 

Interpreter, 1 

italics, 13 



K 



keywords, 44, 50 



M - - 

machine language subroutine, 17 
machine level environment, 121 
mantissa, 7 

MATCH function, 58-59 
mathematical operators, 10 
memory allocation, 121 
MID$ function, 60 
minus sign, 113 
mixed-mode expression, 10 
mnemonic relational operators, 11 
multiple statements, 2 
multiple-statement function, 105 
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LE operator, 10 

leading sign, 113 

LEFTS function, 53 

LEN function, 54 

LET statement, 55 

line numbers, 1 

line-editing functions, 107 

listing control, 133 

literal character, 114 

literal data, 107 

local variables, 104 

LOG function, 56 

logical operators, 11 

lower-case letters, 13 

LPRINTER, 108 

LPRINTER statement, 50, 57, 69-70, 

108, 139 
LT operator, 10 



names, 5 

variable, 5 

user-defined function, 5 
NE operator, 10 
nested functions, 105 
NEXT statement, 38, 61 
nonsubscripted variables, 22 
NOT operator, 10, 11 
numbers, 

integer, 7 

real, 7 
numeric constants, 5, 12, 49 
numeric data field, 111-114 



o 



ON Statement, 62-63, 79, 137 
OPEN statement, 28, 45, 64-65, 119, 

134 
operators, hierarchy of, 10 
optional title field, 140 
OR operator, 10-11 
ORG address, 127 
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OUT predefined function, 108 
OUT statement, 66 
overflow, 12 



passing parameters, 125 
PEEK function, 67, 68, 85 
POKE statement, 25, 68, 85, 128 
POS function, 57, 69, 108 
power operator, 10-11 
PRINT #, 115, 118, 119 
PRINT statement, 57, 70, 95, 108, 134 
PRINT USING statement, 73, 108, 
115, 119 
# variation, 108 
printing, 108 



Q 

quotation mark, 6 



R 



random access files, 65 
RANDOMIZE statement, 74, 84 
READ ft, 76, 116, 118, 119 
READ LINE statement, 77 
READ statement, 29, 75, 107, 134 
Real Constant Area, 121, 122 
real constants, 7 
real numbers, 7-12 
RECL expression, 28, 64, 76 
records, 114 

relational operators, 10, 11 
relative files, 117 

random access to, 117- - 
relative record number, 117* 
REM statement, 22, 79 
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REMARK statement, 79 
RENAME function, 80 
RESTORE statement, 81, 107 
RETURN statement, 35, 82, 105 
RIGHTS function, 82 
RND function, 84 
run-time debugging, 136 
run-time Interpreter, 122 

starting, 4 
Run-time messages, 

error codes, 144-148 

warning messages, 149 

warning codes, 150 



SADD function, 85 

SAVEMEM statement, 86, 124 

sequential files, 115 

SGN function, 88 

SIN function, 89 

single-statement function, 104 

SIZE function, 90 

source programs, 1 

spaces, 2 

SQR Function, 92 

statement labels, 1 

statement numbers, 62 

STEP expression, 38 

STOP, 21 

STOP statement, 49, 70, 93 

STR$ function, 94 

stream organization, 115 

strings, 6, 124 

string constants, 6 

string data field, 109 

string length, 6 

string variables, 8-9, 77, 99 

subroutines, 41, 82 

subscript, 9 





subscript list, expressions in, 9 
subscripted variables, 9, 23, 49, 99 



TAB function, 95, 108 
TAN function, 96 
THEN statement, 43, 45 
TO expression, 38 
TO statement, 42 
toggles 

A, 141 

B, 136, 141 

C, 136, 141 

D, 136, 141 

E, 136, 141 

F, 136, 141 

F, 137, 141 
functions, 135 

G, 137, 141 
H, 141 

TRACE option, 21, 139 
trailing sign, 113 
Transient Program Area, 121 
typographical conventions, 13 



u 

UCASE$ function, 97 
unsubscripted variables, 36 
up arrow, 111 
user-defined functions, 106 



variables, 5-9," 497 102 
VARPTR function, 99 



w 

WEND statement, 100, 102 
WHILE statement, 100, 102 
WIDTH expression, 57 

X 

XOR operator, 10, 11 
XREF file, 140 



$, 5, 103 

floating, 112 



%, 5, 103, 133 
%CHAIN Directive, 134 
%CHAIN directive, 134 
%EJECT directive, 133 
%INCLUDE directive, 133 
%INCLUDE Directive, 134 
%LIST Directive, 133 
%NOLIST Directive, 133 
%PAGE directive, 133 
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VAL function, 98 
Variable Storage Area, 121 
variable-length string field, 108 
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